feat(k8s): add opt-in multi-replica Claude control plane

.env.example

@@ -16,3 +16,11 @@ HOST=0.0.0.0
 # PUBLIC_BASE_URL=https://example.com
 # PUBLIC_HOST=127.0.0.1
 # GITHUB_TOKEN=          # 可选。面板查 GitHub Release 提高限额；也可用 VM2API_GITHUB_TOKEN
+
+# PostgreSQL 17. The installer fills a random password for a new local database.
+# External PG: set VM2API_DATABASE_URL and clear COMPOSE_PROFILES.
+COMPOSE_PROFILES=postgres
+VM2API_POSTGRES_PORT=55432
+VM2API_POSTGRES_PASSWORD=
+VM2API_DATABASE_URL=
+# Preserve VM2API_DB_SECRET when importing an existing SQLite database.

.github/workflows/test.yml

@@ -1,5 +1,4 @@
-# PR/main gate against the production baseline: deploy/payload.json pins the
-# exact ELFs running live, so CI only checks source and the pinned bytes.
+# PR/main gate: Node + Go + pinned amd64 payload ELFs + web + native ARM64 deployment.
 name: ci
 
 on:
@@ -8,19 +7,30 @@ on:
   pull_request:
   workflow_dispatch:
 
-# Only PR runs supersede each other; every main push keeps its own verdict so
-# it is visible when main turned red and when it recovered.
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: true
 
 permissions:
   contents: read
 
 jobs:
-  ci:
+  unit:
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:17-bookworm
+        env:
+          POSTGRES_USER: vm2api
+          POSTGRES_PASSWORD: vm2api-ci-test
+          POSTGRES_DB: vm2api_test
+        ports: [5432:5432]
+        options: >-
+          --health-cmd "pg_isready -U vm2api -d vm2api_test"
+          --health-interval 5s --health-timeout 3s --health-retries 12
+    env:
+      VM2API_TEST_DATABASE_URL: postgresql://vm2api:vm2api-ci-test@127.0.0.1:5432/vm2api_test
     steps:
       - uses: actions/checkout@v7
         with:
@@ -45,30 +55,82 @@ jobs:
           cache-dependency-path: |
             worker/go.sum
             api-kernel/go.sum
-      - uses: pnpm/action-setup@v6
-        with:
-          version: 10
-          cache: true
-          cache_dependency_path: web/pnpm-lock.yaml
+      - name: download worker modules for offline Go protocol fixtures
+        working-directory: worker
+        run: go mod download
       - run: npm ci
-      - name: format and syntax
+      - name: PostgreSQL 17 backup clients
+        run: |
+          sudo install -d /usr/share/postgresql-common/pgdg
+          curl --fail --silent --show-error https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo tee /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc >/dev/null
+          . /etc/os-release
+          echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $VERSION_CODENAME-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list >/dev/null
+          sudo apt-get update
+          sudo apt-get install -y postgresql-client-17 python3-yaml
+          echo /usr/lib/postgresql/17/bin >> "$GITHUB_PATH"
+          /usr/lib/postgresql/17/bin/pg_dump --version
+      - name: pinned Kubernetes manifest tooling
+        run: |
+          curl --fail --silent --show-error --location -o "$RUNNER_TEMP/kubectl" https://dl.k8s.io/release/v1.36.4/bin/linux/amd64/kubectl
+          curl --fail --silent --show-error --location -o "$RUNNER_TEMP/kubectl.sha256" https://dl.k8s.io/release/v1.36.4/bin/linux/amd64/kubectl.sha256
+          python3 -c 'import hashlib,os,pathlib; root=pathlib.Path(os.environ["RUNNER_TEMP"]); assert hashlib.sha256((root/"kubectl").read_bytes()).hexdigest()==(root/"kubectl.sha256").read_text().strip()'
+          chmod 755 "$RUNNER_TEMP/kubectl"
+          echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
+      - name: panel user and onboarding regression tests
+        run: node --import ./test/pg-setup.mjs --test test/unit/panel-users.test.mjs test/unit/onboarding.test.mjs test/e2e/panel-users.e2e.test.mjs
+      - name: format-check
+        run: npx biome format
+      - name: syntax-check Node source and scripts
         run: |
-          npx biome format
-          test -z "$(gofmt -l worker api-kernel)" || { gofmt -l worker api-kernel; exit 1; }
           find src scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check
-      - name: pinned payload
+      - name: slot payloads and egress helper used by the unit tests
         run: |
-          node scripts/fetch-payload.mjs
-          node scripts/fetch-payload.mjs --check
+          npm run fetch:payload
+          npm run build:egress
       - run: npm run test:unit
+      - run: npm run test:e2e
+      - name: ARM64 host preparation and rollback tests
+        run: /usr/bin/python3 -m unittest discover -s test/deploy -v
+      - name: PostgreSQL application role permissions
+        run: python3 test/deploy/smoke_postgres_role.py
       - name: go vet and test
         run: |
           (cd worker && go vet ./... && go test ./...)
           (cd api-kernel && go vet ./... && go test ./...)
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
       - name: web
         working-directory: web
         run: |
           pnpm install --frozen-lockfile
           pnpm format:check
           pnpm test
           pnpm build
+
+  arm64:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - name: prepare pinned x86 QEMU handler
+        run: |
+          python3 deploy/prepare-arm64.py
+          python3 deploy/prepare-arm64.py --check
+          python3 deploy/prepare-arm64.py
+      - name: verify real kernel rollback on the disposable runner
+        run: python3 test/deploy/smoke_binfmt_restore.py
+      - name: validate ARM64 Compose configuration
+        run: |
+          python3 deploy/init-arm64-env.py --port 18787 --container-name vm2api-arm64-ci
+          docker compose -f docker-compose.yml -f docker-compose.arm64.yml config --quiet
+      - name: build native control plane
+        run: docker build --progress=plain --platform linux/arm64 -f deploy/Dockerfile.arm64-control -t vm2api-arm64-control:ci .
+      - name: verify native runtime and emulated payloads
+        run: python3 test/deploy/smoke_arm64_image.py vm2api-arm64-control:ci
+      - name: build and verify a different checkout VERSION
+        run: |
+          trap 'git restore -- VERSION' EXIT
+          python3 -c 'from pathlib import Path; p = Path("VERSION"); p.write_text(p.read_text().strip() + "-arm64-build-check\n")'
+          docker build --progress=plain --platform linux/arm64 -f deploy/Dockerfile.arm64-control -t vm2api-arm64-control:ci-version .
+          python3 test/deploy/smoke_arm64_image.py vm2api-arm64-control:ci-version

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 未发布
+
+- 本地开发分支保留 PostgreSQL、Kubernetes/HA、账号隔离以及官方透传与出站会话重建改动。
+- 保留 Claude 订阅列表、卡片和详情查询功能。查询 sessionKey 独立加密保存；本轮保留已知的 PUT 删除竞争和 HA 订阅接口未接入问题。
+- 使用新增 PostgreSQL 迁移 `023_usage_logs_image_generation.sql` 适配上游图像用量字段；既有 `001`–`022` 迁移不变。
+
 ## 1.4.011 — 2026-10-27
 
 - #736：修复 KVM 槽在关机或「恢复服务」时因换镜像重建容器却未回填 `KIN_KVM_MAC` / `KIN_KVM_DISK_SERIAL` 导致 kin-kvm 启动失败；停/启与恢复路径会从槽配置、旧容器 env 或已采集的 guest hardware 回填并写回 `vm.machine`，env 不完整的容器会强制重建。

Dockerfile

@@ -1,6 +1,7 @@
 # Control plane. Only source is in git: the console and kin-api-kernel build here; the
 # slot payloads and Go helpers come from the release pinned in deploy/payload.json.
 
+ARG BUILDPLATFORM=linux/amd64
 FROM --platform=$BUILDPLATFORM node:22-bookworm-slim AS web
 RUN npm install -g pnpm@10
 WORKDIR /src/web
@@ -27,6 +28,17 @@ FROM node:22-bookworm-slim
 RUN apt-get update \
   && apt-get install -y --no-install-recommends ca-certificates iptables iproute2 python3 \
   && rm -rf /var/lib/apt/lists/*
+# Debian Bookworm defaults to PG15; backups require the PG17 client.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates \
+    && install -d /usr/share/postgresql-common/pgdg \
+    && curl --fail --silent --show-error -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc \
+    && echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt bookworm-pgdg main" > /etc/apt/sources.list.d/pgdg.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends postgresql-client-17 \
+    && pg_dump --version | grep -E ' 17\.' \
+    && pg_restore --version | grep -E ' 17\.' \
+    && rm -rf /var/lib/apt/lists/*
 COPY --from=docker:27-cli /usr/local/bin/docker /usr/local/bin/docker
 WORKDIR /opt/vm2api
 COPY package.json package-lock.json ./

README.md

@@ -213,6 +213,9 @@ chmod 600 .env
 docker compose pull && docker compose up -d
 ```
 
+数据库使用 PostgreSQL 17。新安装由安装脚本生成内置数据库密码；手工 Compose 安装先配置 `.env` 中的 `VM2API_POSTGRES_PASSWORD`。已有 SQLite 安装须先离线导入，保留原 `VM2API_DB_SECRET`。外部数据库、备份恢复和验证步骤见 [PostgreSQL 部署说明](docs/deploy/postgresql.md)。
+
+
 ### 3. 访问与调用
 
 服务启动后，系统暴露统一服务端口（默认 `8787`）：

api-kernel/internal/server/server.go

@@ -4,6 +4,7 @@ import (
 	"crypto/subtle"
 	"encoding/json"
 	"io"
+	"mime"
 	"net/http"
 	"strings"
 
@@ -94,7 +95,33 @@ func (s *Server) forward(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 	w.WriteHeader(resp.StatusCode)
-	_, _ = io.Copy(w, resp.Body)
+	mediaType, _, _ := mime.ParseMediaType(resp.Header.Get("Content-Type"))
+	if mediaType == "text/event-stream" {
+		if flusher, ok := w.(http.Flusher); ok {
+			flusher.Flush()
+			if _, err := io.Copy(flushingWriter{writer: w, flusher: flusher}, resp.Body); err != nil {
+				panic(http.ErrAbortHandler)
+			}
+			return
+		}
+	}
+	if _, err := io.Copy(w, resp.Body); err != nil {
+		panic(http.ErrAbortHandler)
+	}
+}
+
+// Expose only Write so io.Copy cannot bypass flushing through ReaderFrom.
+type flushingWriter struct {
+	writer  io.Writer
+	flusher http.Flusher
+}
+
+func (w flushingWriter) Write(p []byte) (int, error) {
+	n, err := w.writer.Write(p)
+	if n > 0 {
+		w.flusher.Flush()
+	}
+	return n, err
 }
 
 func jsonQuote(s string) string {

api-kernel/internal/server/server_test.go

@@ -1,12 +1,15 @@
 package server
 
 import (
+	"bufio"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/dofastted/kin-gateway/api-kernel/internal/pool"
 )
@@ -43,3 +46,102 @@ func TestForwardCopiesUpstream(t *testing.T) {
 		t.Fatalf("body %s", rec.Body.String())
 	}
 }
+
+func TestForwardStreamsTextDeltasBeforeUpstreamCompletes(t *testing.T) {
+	allowSecond := make(chan struct{}, 1)
+	up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
+		_, _ = io.WriteString(w, "data: {\"type\":\"content_block_delta\",\"delta\":{\"type\":\"text_delta\",\"text\":\"first\"}}\n\n")
+		w.(http.Flusher).Flush()
+		select {
+		case <-allowSecond:
+		case <-r.Context().Done():
+			return
+		}
+		_, _ = io.WriteString(w, "data: {\"type\":\"content_block_delta\",\"delta\":{\"type\":\"text_delta\",\"text\":\"second\"}}\n\n")
+		w.(http.Flusher).Flush()
+	}))
+	defer up.Close()
+
+	gateway := httptest.NewServer((&Server{Token: "t", Pool: pool.NewManager()}).Handler())
+	defer gateway.Close()
+	defer close(allowSecond)
+	env, _ := json.Marshal(forwardEnv{URL: up.URL, Body: `{}`})
+	req, _ := http.NewRequest(http.MethodPost, gateway.URL+"/internal/forward", strings.NewReader(string(env)))
+	req.Header.Set("X-Kin-Internal-Token", "t")
+	client := gateway.Client()
+	client.Timeout = 3 * time.Second
+	type firstRead struct {
+		response *http.Response
+		reader   *bufio.Reader
+		line     string
+		err      error
+	}
+	first := make(chan firstRead, 1)
+	go func() {
+		resp, err := client.Do(req)
+		if err != nil {
+			first <- firstRead{err: err}
+			return
+		}
+		reader := bufio.NewReader(resp.Body)
+		line, err := reader.ReadString('\n')
+		first <- firstRead{response: resp, reader: reader, line: line, err: err}
+	}()
+
+	var got firstRead
+	select {
+	case got = <-first:
+		if got.response != nil {
+			defer got.response.Body.Close()
+		}
+		if got.err != nil {
+			t.Fatal(got.err)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("first nonempty text delta was buffered while the upstream awaited the second delta")
+	}
+	if got.response.StatusCode != http.StatusOK || !strings.Contains(got.line, `"text":"first"`) {
+		t.Fatalf("unexpected first delta: status=%d line=%q", got.response.StatusCode, got.line)
+	}
+	allowSecond <- struct{}{}
+	rest, err := io.ReadAll(got.reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(rest), `"text":"second"`) {
+		t.Fatalf("missing second text delta: %q", rest)
+	}
+}
+
+func TestForwardDoesNotTurnTruncatedUpstreamIntoCleanEOF(t *testing.T) {
+	for _, contentType := range []string{"application/json", "text/event-stream"} {
+		t.Run(contentType, func(t *testing.T) {
+			up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				conn, writer, err := w.(http.Hijacker).Hijack()
+				if err != nil {
+					t.Error(err)
+					return
+				}
+				defer conn.Close()
+				_, _ = fmt.Fprintf(writer, "HTTP/1.1 200 OK\r\nContent-Type: %s\r\nTransfer-Encoding: chunked\r\n\r\nc\r\npartial body\r\n", contentType)
+				_ = writer.Flush() // Deliberately omit the final chunk.
+			}))
+			defer up.Close()
+			gateway := httptest.NewServer((&Server{Token: "t", Pool: pool.NewManager()}).Handler())
+			defer gateway.Close()
+			env, _ := json.Marshal(forwardEnv{URL: up.URL, Body: `{}`})
+			req, _ := http.NewRequest(http.MethodPost, gateway.URL+"/internal/forward", strings.NewReader(string(env)))
+			req.Header.Set("X-Kin-Internal-Token", "t")
+			resp, err := gateway.Client().Do(req)
+			if err != nil {
+				return // Aborting before headers also preserves the transport failure.
+			}
+			defer resp.Body.Close()
+			_, err = io.ReadAll(resp.Body)
+			if err == nil {
+				t.Fatal("truncated upstream was reported as a clean downstream EOF")
+			}
+		})
+	}
+}

deploy/Dockerfile.arm64-control

@@ -40,6 +40,17 @@ FROM --platform=linux/arm64 ${NODE_IMAGE}
 RUN apt-get update \
     && apt-get install -y --no-install-recommends ca-certificates iptables iproute2 python3 \
     && rm -rf /var/lib/apt/lists/*
+# Debian Bookworm defaults to PG15; backups require the PG17 client.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates \
+    && install -d /usr/share/postgresql-common/pgdg \
+    && curl --fail --silent --show-error -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc \
+    && echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt bookworm-pgdg main" > /etc/apt/sources.list.d/pgdg.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends postgresql-client-17 \
+    && pg_dump --version | grep -E ' 17\.' \
+    && pg_restore --version | grep -E ' 17\.' \
+    && rm -rf /var/lib/apt/lists/*
 COPY --from=dockercli /usr/local/bin/docker /usr/local/bin/docker
 WORKDIR /opt/vm2api
 COPY package.json package-lock.json ./