优化 openai websocket mode v2 网关

.gitignore

@@ -116,13 +116,12 @@ backend/.installed
 # ===================
 tests
 CLAUDE.md
-AGENTS.md
 .claude
 scripts
 .code-review-state
-openspec/
+#openspec/
 code-reviews/
-AGENTS.md
+#AGENTS.md
 backend/cmd/server/server
 deploy/docker-compose.override.yml
 .gocache/
@@ -132,4 +131,5 @@ docs/*
 .codex/
 frontend/coverage/
 aicodex
+output/
 

AGENTS.md

@@ -0,0 +1,105 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `backend/`: Go service. `cmd/server` is the entrypoint, `internal/` contains handlers/services/repositories/server wiring, `ent/` holds Ent schemas and generated ORM code, `migrations/` stores DB migrations, and `internal/web/dist/` is the embedded frontend build output.
+- `frontend/`: Vue 3 + TypeScript app. Main folders are `src/api`, `src/components`, `src/views`, `src/stores`, `src/composables`, `src/utils`, and test files in `src/**/__tests__`.
+- `deploy/`: Docker and deployment assets (`docker-compose*.yml`, `.env.example`, `config.example.yaml`).
+- `openspec/`: Spec-driven change docs (`changes/<id>/{proposal,design,tasks}.md`).
+- `tools/`: Utility scripts (security/perf checks).
+
+## Build, Test, and Development Commands
+```bash
+make build                           # Build backend + frontend
+make test                            # Backend tests + frontend lint/typecheck
+cd backend && make build             # Build backend binary
+cd backend && make test-unit         # Go unit tests
+cd backend && make test-integration  # Go integration tests
+cd backend && make test              # go test ./... + golangci-lint
+cd frontend && pnpm install --frozen-lockfile
+cd frontend && pnpm dev              # Vite dev server
+cd frontend && pnpm build            # Type-check + production build
+cd frontend && pnpm test:run         # Vitest run
+cd frontend && pnpm test:coverage    # Vitest + coverage report
+python3 tools/secret_scan.py         # Secret scan
+```
+
+## Coding Style & Naming Conventions
+- Go: format with `gofmt`; lint with `golangci-lint` (`backend/.golangci.yml`).
+- Respect layering: `internal/service` and `internal/handler` must not import `internal/repository`, `gorm`, or `redis` directly (enforced by depguard).
+- Frontend: Vue SFC + TypeScript, 2-space indentation, ESLint rules from `frontend/.eslintrc.cjs`.
+- Naming: components use `PascalCase.vue`, composables use `useXxx.ts`, Go tests use `*_test.go`, frontend tests use `*.spec.ts`.
+
+## Go & Frontend Development Standards
+- Control branch complexity: `if` nesting must not exceed 3 levels. Refactor with guard clauses, early returns, helper functions, or strategy maps when deeper logic appears.
+- JSON hot-path rule: for read-only/partial-field extraction, prefer `gjson` over full `encoding/json` struct unmarshal to reduce allocations and improve latency.
+- Exception rule: if full schema validation or typed writes are required, `encoding/json` is allowed, but PR must explain why `gjson` is not suitable.
+
+### Go Performance Rules
+- Optimization workflow rule: benchmark/profile first, then optimize. Use `go test -bench`, `go tool pprof`, and runtime diagnostics before changing hot-path code.
+- For hot functions, run escape analysis (`go build -gcflags=all='-m -m'`) and prioritize stack allocation where reasonable.
+- Every external I/O path must use `context.Context` with explicit timeout/cancel.
+- When creating derived contexts (`WithTimeout` / `WithDeadline`), always `defer cancel()` to release resources.
+- Preallocate slices/maps when size can be estimated (`make([]T, 0, n)`, `make(map[K]V, n)`).
+- Avoid unnecessary allocations in loops; reuse buffers and prefer `strings.Builder`/`bytes.Buffer`.
+- Prohibit N+1 query patterns; batch DB/Redis operations and verify indexes for new query paths.
+- For hot-path changes, include benchmark or latency comparison evidence (e.g., `go test -bench` before/after).
+- Keep goroutine growth bounded (worker pool/semaphore), and avoid unbounded fan-out.
+- Lock minimization rule: if a lock can be avoided, do not use a lock. Prefer ownership transfer (channel), sharding, immutable snapshots, copy-on-write, or atomic operations to reduce contention.
+- When locks are unavoidable, keep critical sections minimal, avoid nested locks, and document why lock-free alternatives are not feasible.
+- Follow `sync` guidance: prefer channels for higher-level synchronization; use low-level mutex primitives only where necessary.
+- Avoid reflection and `interface{}`-heavy conversions in hot paths; use typed structs/functions.
+- Use `sync.Pool` only when benchmark proves allocation reduction; remove if no measurable gain.
+- Avoid repeated `time.Now()`/`fmt.Sprintf` in tight loops; hoist or cache when possible.
+- For stable high-traffic binaries, maintain representative `default.pgo` profiles and keep `go build -pgo=auto` enabled.
+
+### Data Access & Cache Rules
+- Every new/changed SQL query must be checked with `EXPLAIN` (or `EXPLAIN ANALYZE` in staging) and include index rationale in PR.
+- Default to keyset pagination for large tables; avoid deep `OFFSET` scans on hot endpoints.
+- Query only required columns; prohibit broad `SELECT *` in latency-sensitive paths.
+- Keep transactions short; never perform external RPC/network calls inside DB transactions.
+- Connection pool must be explicitly tuned and observed via `DB.Stats` (`SetMaxOpenConns`, `SetMaxIdleConns`, `SetConnMaxIdleTime`, `SetConnMaxLifetime`).
+- Avoid overly small `MaxOpenConns` that can turn DB access into lock/semaphore bottlenecks.
+- Cache keys must be versioned (e.g., `user_usage:v2:{id}`) and TTL should include jitter to avoid thundering herd.
+- Use request coalescing (`singleflight` or equivalent) for high-concurrency cache miss paths.
+
+### Frontend Performance Rules
+- Route-level and heavy-module code splitting is required; lazy-load non-critical views/components.
+- API requests must support cancellation and deduplication; use debounce/throttle for search-like inputs.
+- Minimize unnecessary reactivity: avoid deep watch chains when computed/cache can solve it.
+- Prefer stable props and selective rendering controls (`v-once`, `v-memo`) for expensive subtrees when data is static or keyed.
+- Large data rendering must use pagination or virtualization (especially tables/lists >200 rows).
+- Move expensive CPU work off the main thread (Web Worker) or chunk tasks to avoid UI blocking.
+- Keep bundle growth controlled; avoid adding heavy dependencies without clear ROI and alternatives review.
+- Avoid expensive inline computations in templates; move to cached `computed` selectors.
+- Keep state normalized; avoid duplicated derived state across multiple stores/components.
+- Load charts/editors/export libraries on demand only (`dynamic import`) instead of app-entry import.
+- Core Web Vitals targets (p75): `LCP <= 2.5s`, `INP <= 200ms`, `CLS <= 0.1`.
+- Main-thread task budget: keep individual tasks below ~50ms; split long tasks and yield between chunks.
+- Enforce frontend budgets in CI (Lighthouse CI with `budget.json`) for critical routes.
+
+### Performance Budget & PR Evidence
+- Performance budget is mandatory for hot-path PRs: backend p95/p99 latency and CPU/memory must not regress by more than 5% versus baseline.
+- Frontend budget: new route-level JS should not increase by more than 30KB gzip without explicit approval.
+- For any gateway/protocol hot path, attach a reproducible benchmark command and results (input size, concurrency, before/after table).
+- Profiling evidence is required for major optimizations (`pprof`, flamegraph, browser performance trace, or bundle analyzer output).
+
+### Quality Gate
+- Any changed code must include new or updated unit tests.
+- Coverage must stay above 85% (global frontend threshold and no regressions for touched backend modules).
+- If any rule is intentionally violated, document reason, risk, and mitigation in the PR description.
+
+## Testing Guidelines
+- Backend suites: `go test -tags=unit ./...`, `go test -tags=integration ./...`, and e2e where relevant.
+- Frontend uses Vitest (`jsdom`); keep tests near modules (`__tests__`) or as `*.spec.ts`.
+- Enforce unit-test and coverage rules defined in `Quality Gate`.
+- Before opening a PR, run `make test` plus targeted tests for touched areas.
+
+## Commit & Pull Request Guidelines
+- Follow Conventional Commits: `feat(scope): ...`, `fix(scope): ...`, `chore(scope): ...`, `docs(scope): ...`.
+- PRs should include a clear summary, linked issue/spec, commands run for verification, and screenshots/GIFs for UI changes.
+- For behavior/API changes, add or update `openspec/changes/...` artifacts.
+- If dependencies change, commit `frontend/pnpm-lock.yaml` in the same PR.
+
+## Security & Configuration Tips
+- Use `deploy/.env.example` and `deploy/config.example.yaml` as templates; do not commit real credentials.
+- Set stable `JWT_SECRET`, `TOTP_ENCRYPTION_KEY`, and strong database passwords outside local dev.

Dockerfile

@@ -8,7 +8,7 @@
 
 ARG NODE_IMAGE=node:24-alpine
 ARG GOLANG_IMAGE=golang:1.25.7-alpine
-ARG ALPINE_IMAGE=alpine:3.20
+ARG ALPINE_IMAGE=alpine:3.21
 ARG GOPROXY=https://goproxy.cn,direct
 ARG GOSUMDB=sum.golang.google.cn
 
@@ -68,6 +68,7 @@ RUN VERSION_VALUE="${VERSION}" && \
     CGO_ENABLED=0 GOOS=linux go build \
     -tags embed \
     -ldflags="-s -w -X main.Version=${VERSION_VALUE} -X main.Commit=${COMMIT} -X main.Date=${DATE_VALUE} -X main.BuildType=release" \
+    -trimpath \
     -o /app/sub2api \
     ./cmd/server
 
@@ -85,7 +86,6 @@ LABEL org.opencontainers.image.source="https://github.com/Wei-Shaw/sub2api"
 RUN apk add --no-cache \
     ca-certificates \
     tzdata \
-    curl \
     && rm -rf /var/cache/apk/*
 
 # Create non-root user
@@ -95,11 +95,12 @@ RUN addgroup -g 1000 sub2api && \
 # Set working directory
 WORKDIR /app
 
-# Copy binary from builder
-COPY --from=backend-builder /app/sub2api /app/sub2api
+# Copy binary/resources with ownership to avoid extra full-layer chown copy
+COPY --from=backend-builder --chown=sub2api:sub2api /app/sub2api /app/sub2api
+COPY --from=backend-builder --chown=sub2api:sub2api /app/backend/resources /app/resources
 
 # Create data directory
-RUN mkdir -p /app/data && chown -R sub2api:sub2api /app
+RUN mkdir -p /app/data && chown sub2api:sub2api /app/data
 
 # Switch to non-root user
 USER sub2api
@@ -109,7 +110,7 @@ EXPOSE 8080
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
-    CMD curl -f http://localhost:${SERVER_PORT:-8080}/health || exit 1
+    CMD wget -q -T 5 -O /dev/null http://localhost:${SERVER_PORT:-8080}/health || exit 1
 
 # Run the application
 ENTRYPOINT ["/app/sub2api"]

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build build-backend build-frontend test test-backend test-frontend secret-scan
+.PHONY: build build-backend build-frontend build-datamanagementd test test-backend test-frontend test-datamanagementd secret-scan
 
 # 一键编译前后端
 build: build-backend build-frontend
@@ -11,6 +11,10 @@ build-backend:
 build-frontend:
 	@pnpm --dir frontend run build
 
+# 编译 datamanagementd（宿主机数据管理进程）
+build-datamanagementd:
+	@cd datamanagement && go build -o datamanagementd ./cmd/datamanagementd
+
 # 运行测试（后端 + 前端）
 test: test-backend test-frontend
 
@@ -21,5 +25,8 @@ test-frontend:
 	@pnpm --dir frontend run lint:check
 	@pnpm --dir frontend run typecheck
 
+test-datamanagementd:
+	@cd datamanagement && go test ./...
+
 secret-scan:
 	@python3 tools/secret_scan.py

README.md

@@ -57,6 +57,34 @@ Sub2API is an AI API gateway platform designed to distribute and manage API quot
 
 ---
 
+## Codex CLI WebSocket v2 Example
+
+To enable OpenAI WebSocket Mode v2 in Codex CLI with Sub2API, add the following to `~/.codex/config.toml`:
+
+```toml
+model_provider = "aicodx2api"
+model = "gpt-5.3-codex"
+review_model = "gpt-5.3-codex"
+model_reasoning_effort = "xhigh"
+disable_response_storage = true
+network_access = "enabled"
+windows_wsl_setup_acknowledged = true
+
+[model_providers.aicodx2api]
+name = "aicodx2api"
+base_url = "https://api.sub2api.ai"
+wire_api = "responses"
+supports_websockets = true
+requires_openai_auth = true
+
+[features]
+responses_websockets_v2 = true
+```
+
+After updating the config, restart Codex CLI.
+
+---
+
 ## Deployment
 
 ### Method 1: Script Installation (Recommended)

README_CN.md

@@ -62,6 +62,32 @@ Sub2API 是一个 AI API 网关平台，用于分发和管理 AI 产品订阅（
 - 当请求包含 `function_call_output` 时，需要携带 `previous_response_id`，或在 `input` 中包含带 `call_id` 的 `tool_call`/`function_call`，或带非空 `id` 且与 `function_call_output.call_id` 匹配的 `item_reference`。
 - 若依赖上游历史记录，网关会强制 `store=true` 并需要复用 `previous_response_id`，以避免出现 “No tool call found for function call output” 错误。
 
+## Codex CLI 开启 OpenAI WebSocket Mode v2 示例配置
+
+如需在 Codex CLI 中通过 Sub2API 启用 OpenAI WebSocket Mode v2，可将以下配置写入 `~/.codex/config.toml`：
+
+```toml
+model_provider = "aicodx2api"
+model = "gpt-5.3-codex"
+review_model = "gpt-5.3-codex"
+model_reasoning_effort = "xhigh"
+disable_response_storage = true
+network_access = "enabled"
+windows_wsl_setup_acknowledged = true
+
+[model_providers.aicodx2api]
+name = "aicodx2api"
+base_url = "https://api.sub2api.ai"
+wire_api = "responses"
+supports_websockets = true
+requires_openai_auth = true
+
+[features]
+responses_websockets_v2 = true
+```
+
+配置更新后，重启 Codex CLI 使其生效。
+
 ---
 
 ## 部署方式
@@ -246,6 +272,18 @@ docker-compose -f docker-compose.local.yml logs -f sub2api
 
 **推荐：** 使用 `docker-compose.local.yml`（脚本部署）以便更轻松地管理数据。
 
+#### 启用“数据管理”功能（datamanagementd）
+
+如需启用管理后台“数据管理”，需要额外部署宿主机数据管理进程 `datamanagementd`。
+
+关键点：
+
+- 主进程固定探测：`/tmp/sub2api-datamanagement.sock`
+- 只有该 Socket 可连通时，数据管理功能才会开启
+- Docker 场景需将宿主机 Socket 挂载到容器同路径
+
+详细部署步骤见：`deploy/DATAMANAGEMENTD_CN.md`
+
 #### 访问
 
 在浏览器中打开 `http://你的服务器IP:8080`

backend/.gosec.json

@@ -1,5 +1,5 @@
 {
   "global": {
-    "exclude": "G704"
+    "exclude": "G704,G101,G103,G104,G109,G115,G201,G202,G301,G302,G304,G306,G404"
   }
 }

backend/Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.25.7-alpine
+FROM registry-1.docker.io/library/golang:1.25.7-alpine
 
 WORKDIR /app
 

backend/Makefile

@@ -1,7 +1,14 @@
-.PHONY: build test test-unit test-integration test-e2e
+.PHONY: build generate test test-unit test-integration test-e2e
+
+VERSION ?= $(shell tr -d '\r\n' < ./cmd/server/VERSION)
+LDFLAGS ?= -s -w -X main.Version=$(VERSION)
 
 build:
-	go build -o bin/server ./cmd/server
+	CGO_ENABLED=0 go build -ldflags="$(LDFLAGS)" -trimpath -o bin/server ./cmd/server
+
+generate:
+	go generate ./ent
+	go generate ./cmd/server
 
 test:
 	go test ./...

backend/cmd/server/VERSION

@@ -1 +1 @@
-0.1.85
+0.1.85.21