整合 dev 应用更新与后端数据库可靠性优化

.env.example

@@ -26,19 +26,53 @@ MINIO_ROOT_PASSWORD=
 # Local MinIO only: allowed browser origins for direct presigned POST upload (comma-separated or *)
 # MINIO_API_CORS_ALLOW_ORIGIN=http://localhost:8080,http://127.0.0.1:8080,http://localhost:5173,http://127.0.0.1:5173,http://localhost:3000,http://127.0.0.1:3000
 
-# Image deployment knobs (compose.images.yaml / compose.prod.yaml web-next build):
+# Image deployment knobs (compose.images.yaml / compose.prod.yaml web build):
 # MUSECANVAS_IMAGE_TAG=latest
 # MUSECANVAS_HTTP_PORT=18080
-# Local web-next dev only (apps/web-next/.env.local): point the dev rewrites
+
+# First-run onboarding (/setup) needs a one-time claim code. In production nothing is minted
+# unless you opt in. Set ONE of these for the first install only, then remove it:
+#   SETUP_CLAIM_DELIVERY=log   prints the code once to the API container log
+#                              (docker compose logs api | grep "MUSECANVAS SETUP CLAIM").
+#                              Anyone who can read that log can redeem the code for 15 minutes
+#                              (single use, 5 attempts), so clear the log line after use.
+#   SETUP_CLAIM_DELIVERY=file  writes the code (mode 0600) to SETUP_CLAIM_FILE, a path inside
+#                              the API container; read it with docker compose exec.
+# SETUP_CLAIM_DELIVERY=
+# SETUP_CLAIM_FILE=
+# Leave SETUP_CLAIM_REQUIRED unset (the default) in every normal install: /setup then needs the claim code.
+# SETUP_CLAIM_REQUIRED=false removes the claim code. WARNING: while no admin exists, anyone who can reach
+# /setup can configure SMTP and create the first admin. Use it only on networks you control, and remove
+# it once the first admin exists. The window closes by itself after that, but leave it unset elsewhere.
+# SETUP_CLAIM_REQUIRED=
+# Local web dev only (apps/web/.env.local): point the dev rewrites
 # proxy directly at the API so write requests keep a valid X-Forwarded-Host.
 # API_ORIGIN=http://localhost:3001
-# In containers web-next SSR talks to the API directly via INTERNAL_API_BASE_URL
+# In containers web SSR talks to the API directly via INTERNAL_API_BASE_URL
 # (set by compose); browsers always use the same-origin /api proxied by Nginx.
 # Source/image deployment stacks expect TLS and default cookies to Secure.
 # Set false only when intentionally exposing Nginx directly over plain HTTP.
 # Bundled local stacks default this to false for their documented HTTP ports.
 # COOKIE_SECURE=true
 
+# ===== Backend resource budgets (per process; pool totals scale with replicas) =====
+DATABASE_POOL_MAX=12
+DATABASE_CONNECTION_TIMEOUT_MS=5000
+DATABASE_IDLE_TIMEOUT_MS=30000
+DATABASE_STATEMENT_TIMEOUT_MS=30000
+DATABASE_LOCK_TIMEOUT_MS=5000
+DATABASE_IDLE_TRANSACTION_TIMEOUT_MS=30000
+REDIS_CONNECT_TIMEOUT_MS=1000
+REDIS_COMMAND_TIMEOUT_MS=1000
+WORKER_REDIS_COMMAND_TIMEOUT_MS=5000
+WORKER_CONCURRENCY=2
+WORKER_STORAGE_TIMEOUT_MS=60000
+# Only acknowledged/delivered Stream entries older than this are removed.
+# Pending/unread entries and streams with unknown groups are never trimmed.
+# Set 0 to disable automatic Stream deletion before deploying if required.
+STREAM_RETENTION_SECONDS=604800
+STREAM_TRIM_BATCH_SIZE=1000
+
 # ===== Deployment security policies (default-deny; keep false unless required) =====
 # Plaintext SMTP is only ever needed for the bundled Mailpit, which the
 # bundled Compose files already allow. External deployments must use

.github/workflows/backend-reliability.yml

@@ -0,0 +1,58 @@
+name: Backend reliability fixtures
+
+on:
+  pull_request:
+    branches: [main]
+    paths: ['apps/api/**', 'apps/worker/**', 'packages/database/**', 'tests/integration/backend-reliability*', 'deploy/**', '.github/workflows/backend-reliability.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  fixtures:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: fixture
+          POSTGRES_PASSWORD: fixture-only
+          POSTGRES_DB: postgres
+        ports: ['5432:5432']
+        options: --health-cmd "pg_isready -U fixture -d postgres" --health-interval 3s --health-timeout 3s --health-retries 20
+      redis:
+        image: redis:7.4-alpine
+        ports: ['6379:6379']
+        options: --health-cmd "redis-cli ping" --health-interval 3s --health-timeout 3s --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.23.4
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Validate all Compose variants with synthetic configuration
+        env:
+          POSTGRES_PASSWORD: fixture-only
+          APP_MASTER_KEY: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+          MINIO_ROOT_PASSWORD: fixture-only-password
+        run: |
+          for file in deploy/compose.yaml deploy/compose.dev.yaml deploy/compose.prod.yaml deploy/compose.images.yaml; do
+            docker compose --project-directory . -f "$file" config --quiet
+          done
+      - name: Test real PostgreSQL and Redis behavior in disposable fixtures
+        env:
+          MUSECANVAS_OPTIMIZATION_PG_URL: postgresql://fixture:fixture-only@127.0.0.1:5432/postgres
+          MUSECANVAS_OPTIMIZATION_REDIS_URL: redis://127.0.0.1:6379/15
+        run: pnpm --filter @musecanvas/providers exec tsx --test "../../tests/integration/backend-reliability*.test.ts"
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: synthetic-backend-query-plans
+          path: .runtime/backend-benchmark.json
+          if-no-files-found: ignore

.github/workflows/docker-image.yml

@@ -50,6 +50,7 @@ jobs:
       - name: Rotate password without replacing persistent data
         env:
           COMPOSE_PROJECT_NAME: musecanvas-password-sync
+          # 此为 CI 一次性容器的非生产占位密钥，切勿用于任何真实环境。
           APP_MASTER_KEY: 0000000000000000000000000000000000000000000000000000000000000000
           MINIO_ROOT_PASSWORD: unused-by-password-sync-test
           OLD_PASSWORD: before-password-rotation
@@ -98,8 +99,8 @@ jobs:
             dockerfile: deploy/docker/worker.Dockerfile
             build_args: ""
 
-          - image: musecanvas-web-next
-            dockerfile: deploy/docker/web-next.Dockerfile
+          - image: musecanvas-web
+            dockerfile: deploy/docker/web.Dockerfile
             build_args: ""
 
           - image: musecanvas-nginx

.github/workflows/media-quality.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Set up Node.js with pnpm cache
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 22.23.4
           cache: pnpm
 
       - name: Install dependencies with frozen lockfile (no external services)
@@ -59,6 +59,9 @@ jobs:
       - name: Typecheck workspaces (no external services)
         run: pnpm -r --if-present typecheck
 
+      - name: Lint workspaces (no external services)
+        run: pnpm -r --if-present lint
+
       - name: Test providers package incl. media contract (no external services)
         run: pnpm --filter @musecanvas/providers test
 

.github/workflows/web-checks.yml

@@ -1,6 +1,6 @@
 name: Web Checks CI
 
-# Frontend-only gate for `apps/web-next`.
+# Frontend-only gate for `apps/web`.
 #
 # `media-quality.yml` already runs `pnpm -r --if-present typecheck` and
 # `pnpm -r --if-present build` for every workspace on the same PRs, so the
@@ -11,7 +11,7 @@ name: Web Checks CI
 # a token regression is reported as a token failure rather than as a build error
 # somewhere downstream.
 #
-# The web-next typecheck stays too, scoped with `--filter` (seconds, not minutes) so
+# The web typecheck stays too, scoped with `--filter` (seconds, not minutes) so
 # this workflow is meaningful on its own even if that workflow's path filters change.
 #
 # No secrets, no external services, no image build or push.
@@ -20,7 +20,7 @@ on:
   push:
     branches: ["main"]
     paths:
-      - "apps/web-next/**"
+      - "apps/web/**"
       - "scripts/check-web-tokens.mjs"
       - "package.json"
       - "pnpm-lock.yaml"
@@ -29,7 +29,7 @@ on:
   pull_request:
     branches: ["main"]
     paths:
-      - "apps/web-next/**"
+      - "apps/web/**"
       - "scripts/check-web-tokens.mjs"
       - "package.json"
       - "pnpm-lock.yaml"
@@ -62,7 +62,7 @@ jobs:
       - name: Set up Node.js with pnpm cache
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 22.23.4
           cache: pnpm
 
       - name: Install dependencies with frozen lockfile (no external services)
@@ -72,4 +72,4 @@ jobs:
         run: pnpm check:tokens
 
       - name: Typecheck the web app (no external services)
-        run: pnpm --filter @musecanvas/web-next typecheck
+        run: pnpm --filter @musecanvas/web typecheck

.gitignore

@@ -70,6 +70,7 @@ CLAUDE.md
 .codex/
 .qoder/
 .serena/
+.pi/
 /skills/
 .runtime/
 .zcode/

agents.md

@@ -21,7 +21,7 @@
 MuseCanvas
 ├── apps/
 │   ├── api/          # Next.js 15 (App Router) 核心后端服务 (REST API, 鉴权, 路由)
-│   ├── web-next/     # Next.js 15 (App Router, React 19) + Zustand + TanStack Query 混合渲染前端应用（唯一前端）
+│   ├── web/     # Next.js 15 (App Router, React 19) + Zustand + TanStack Query 混合渲染前端应用（唯一前端）
 │   └── worker/       # Redis Streams + 事务性 Outbox 异步任务消费端 (生成、轮询与维护任务)
 ├── packages/
 │   ├── contracts/    # 共享 DTO (纯 TS 类型)、错误码、类型契约与 API_ENDPOINTS 端点路径常量表 (最底游依赖，无运行时校验库)
@@ -42,9 +42,9 @@ MuseCanvas
 
 ---
 
-## 前端架构与状态设计规范 (Frontend Standards: web-next)
+## 前端架构与状态设计规范 (Frontend Standards: web)
 
-在开发与维护 `apps/web-next` 时，必须严格遵循以下混合渲染与状态管理准则：
+在开发与维护 `apps/web` 时，必须严格遵循以下混合渲染与状态管理准则：
 
 ### 1. 业务驱动的混合渲染矩阵 (Hybrid Rendering Matrix)
 - **公共营销与法律条款页（SSG 纯静态生成）**：
@@ -130,7 +130,7 @@ MuseCanvas
   - 专注于 `apps/worker` 队列消费逻辑与 `packages/providers` 外部集成。
   - 处理异步重试、幂等性、超时控制与任务状态流转。
 - **前端交互 Agent (Frontend Coder)**：
-  - 专注于 `apps/web-next`（Next.js 15 + React 19 + Zustand + TanStack Query）的组件、状态、路由与页面逻辑。
+  - 专注于 `apps/web`（Next.js 15 + React 19 + Zustand + TanStack Query）的组件、状态、路由与页面逻辑。
   - 严格保持与 `contracts` 定义的前后端交互类型一致，遵循混合渲染与双端 API 客户端隔离规范。
 - **代码审查与质检 Agent (Reviewer / QA)**：
   - 对变更实施独立审查，检查安全性、类型健壮性、边界用例覆盖与项目规范符合度。

apps/README.md

@@ -1,6 +1,6 @@
 # Applications
 
-- `web-next`: Next.js 15 (React 19) 用户端和管理员后台。
+- `web`: Next.js 15 (React 19) 用户端和管理员后台。
 - `api`: Next.js API Routes，负责认证、授权和业务接口。
 - `worker`: 独立 TypeScript Worker，负责队列消费和定时任务。
 

apps/api/next.config.ts

@@ -1,4 +1,15 @@
 import type { NextConfig } from 'next'
 
-const config: NextConfig = { serverExternalPackages: ['pg', 'nodemailer', 'sharp'] }
+// `@musecanvas/*` packages export raw `.ts` sources, so Next must compile them
+// rather than treat them as prebuilt externals. `serverExternalPackages` is kept
+// for the native/Node-only deps that must stay outside the bundle.
+const config: NextConfig = {
+  transpilePackages: [
+    '@musecanvas/contracts',
+    '@musecanvas/database',
+    '@musecanvas/domain',
+    '@musecanvas/providers',
+  ],
+  serverExternalPackages: ['pg', 'nodemailer', 'sharp'],
+}
 export default config

apps/api/package.json

@@ -8,7 +8,8 @@
     "build": "next build",
     "start": "next start -p 3001",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test \"src/**/*.test.ts\""
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "lint": "eslint ."
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1073.0",
@@ -19,16 +20,16 @@
     "@musecanvas/domain": "workspace:*",
     "@musecanvas/providers": "workspace:*",
     "jose": "^6.2.3",
-    "next": "^15.5.19",
-    "nodemailer": "^7.0.13",
+    "next": "^15.5.27",
+    "nodemailer": "^10.1.1",
     "pg": "^8.22.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "redis": "^5.12.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",
-    "@types/nodemailer": "^7.0.12",
+    "@types/nodemailer": "^8.0.2",
     "@types/pg": "^8.20.0",
     "@types/react": "19.2.17",
     "tsx": "^4.22.4",