From 71b35b9cc6d051afbad1a4a151fbdff478cfaf43 Mon Sep 17 00:00:00 2001 From: xiaomai Date: Wed, 6 May 2026 16:18:23 +0800 Subject: [PATCH] chore(docker): add local debug compose setup and scripts Add docker-compose.debug.yml for local hot-reload debugging Add docker:debug and docker:prod scripts to package.json Update documentation and environment examples for debug usage Update pnpm version in packageManager field --- .env.example | 6 +++ DESIGN.md | 2 + SSR_MIGRATION_TASKLIST.md | 1 + docker-compose.debug.yml | 110 ++++++++++++++++++++++++++++++++++++++ package.json | 6 ++- 5 files changed, 123 insertions(+), 2 deletions(-) create mode 100644 docker-compose.debug.yml diff --git a/.env.example b/.env.example index 10a68a4..58c3179 100644 --- a/.env.example +++ b/.env.example @@ -20,6 +20,12 @@ RESEND_QUOTA_RESERVE=5 RESEND_QUOTA_SNAPSHOT_TTL_MINUTES=10 AI_MODERATION_API_KEY= +# Local Docker debug defaults: +# docker compose -f docker-compose.debug.yml up --build +# NUXT_PUBLIC_API_BASE_URL=http://localhost:20016 +# NUXT_SERVER_API_BASE_URL=http://backend:3001 +# NUXT_PUBLIC_SITE_URL=http://localhost:20015 + # Cloudflared tunnel deployment example: # FRONTEND_ORIGIN=https://pokopiawiki.tootaio.com,http://localhost:20015 # APP_ORIGIN=https://pokopiawiki.tootaio.com diff --git a/DESIGN.md b/DESIGN.md index c896f27..7c1e739 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1072,6 +1072,7 @@ API 暴露边界： - `frontend` 因 `docker compose up -d --build` 重建、启动中或临时不可达时，`frontend_gateway` 返回静态升级维护页并保持公开端口可访问；后端 `/health` 不可用时，前端网关也返回同一维护页，避免用户看到静态页面后遇到 API 不可用。 - 升级维护页是基础设施级静态 fallback，不依赖 Vue、Vue I18n、后端 API 或数据库；页面只展示正式用户文案和品牌视觉，不展示构建日志、调试信息、内部字段或实现说明。 - 升级维护页使用 `503`、`Retry-After: 300`、`Cache-Control: no-store` 和 `noindex`，提示用户 Pokopia Wiki 正在升级并将在约 5 分钟内恢复。 +- 本地 Docker 调试使用 `docker-compose.debug.yml`，通过 bind mount 运行 Nuxt dev server 与 backend `tsx watch`，支持前后端热重载；该调试入口不经过 `frontend_gateway` 维护页，不代表生产部署行为。 ## API 概览 @@ -1198,3 +1199,4 @@ API 暴露边界： - `pnpm typecheck` - 不在 WSL 中运行测试作为完成任务的前置条件。 - Docker 运行问题以用户提供的 `docker compose up --build` 输出为准进行后续修复。 +- 本地热重载调试可运行 `pnpm docker:debug` 或 `docker compose -f docker-compose.debug.yml up --build`；生产 SSR runtime 验证仍使用 `pnpm docker:prod` 或 `docker compose up --build`。 diff --git a/SSR_MIGRATION_TASKLIST.md b/SSR_MIGRATION_TASKLIST.md index b599fa8..c7b30c3 100644 --- a/SSR_MIGRATION_TASKLIST.md +++ b/SSR_MIGRATION_TASKLIST.md @@ -142,6 +142,7 @@ Keep this file aligned with implementation progress while the SSR migration is i - `frontend/Dockerfile` now runs `node .output/server/index.mjs` with `HOST=0.0.0.0` and `PORT=20015`; the obsolete lightweight static server file was removed. - `frontend_gateway` continues to proxy `frontend:20015` and keep the backend health-gated maintenance fallback independent from Nuxt. - `DESIGN.md` now documents the Nuxt server output deployment model and the existing browser API, server API, site URL, origin, and proxy environment variables. +- `docker-compose.debug.yml` provides a separate local debug path that runs Nuxt dev server and backend `tsx watch` with bind-mounted source; default `docker compose up --build` remains the production SSR runtime validation path. - A local smoke check of `node frontend/.output/server/index.mjs` on port `20115` returned SSR HTML for `/` and `200` for `/robots.txt`; Docker compose runtime validation is still pending. ## Phase 8: Validation diff --git a/docker-compose.debug.yml b/docker-compose.debug.yml new file mode 100644 index 0000000..77eb40f --- /dev/null +++ b/docker-compose.debug.yml @@ -0,0 +1,110 @@ +services: + postgres: + image: postgres:18-alpine + environment: + POSTGRES_DB: pokopia + POSTGRES_USER: pokopia + POSTGRES_PASSWORD: pokopia + volumes: + - postgres18_data:/var/lib/postgresql + healthcheck: + test: ["CMD-SHELL", "pg_isready -U pokopia -d pokopia"] + interval: 5s + timeout: 3s + retries: 10 + + deps: + image: node:22-alpine + working_dir: /app + environment: + PNPM_HOME: /pnpm + volumes: + - .:/app + - root_node_modules:/app/node_modules + - backend_node_modules:/app/backend/node_modules + - frontend_node_modules:/app/frontend/node_modules + - pnpm_store:/pnpm/store + command: > + sh -lc "corepack enable && + corepack prepare pnpm@10.33.2 --activate && + pnpm config set store-dir /pnpm/store && + pnpm install --frozen-lockfile" + + backend: + image: node:22-alpine + working_dir: /app + environment: + NODE_ENV: development + PNPM_HOME: /pnpm + DATABASE_URL: postgres://pokopia:pokopia@postgres:5432/pokopia + BACKEND_PORT: 3001 + TRUST_PROXY: ${TRUST_PROXY:-false} + FRONTEND_ORIGIN: ${FRONTEND_ORIGIN:-http://localhost:20015} + APP_ORIGIN: ${APP_ORIGIN:-http://localhost:20015} + UPLOAD_DIR: /app/uploads + BACKEND_PUBLIC_ORIGIN: ${BACKEND_PUBLIC_ORIGIN:-http://localhost:20016} + RESEND_API_KEY: ${RESEND_API_KEY:-} + EMAIL_FROM: "${EMAIL_FROM:-Pokopia Wiki }" + RESEND_DAILY_QUOTA_LIMIT: ${RESEND_DAILY_QUOTA_LIMIT:-100} + RESEND_MONTHLY_QUOTA_LIMIT: ${RESEND_MONTHLY_QUOTA_LIMIT:-3000} + RESEND_QUOTA_RESERVE: ${RESEND_QUOTA_RESERVE:-5} + RESEND_QUOTA_SNAPSHOT_TTL_MINUTES: ${RESEND_QUOTA_SNAPSHOT_TTL_MINUTES:-10} + AI_MODERATION_API_KEY: ${AI_MODERATION_API_KEY:-} + ports: + - "20016:3001" + volumes: + - .:/app + - root_node_modules:/app/node_modules + - backend_node_modules:/app/backend/node_modules + - frontend_node_modules:/app/frontend/node_modules + - pnpm_store:/pnpm/store + - backend_uploads:/app/uploads + command: > + sh -lc "corepack enable && + corepack prepare pnpm@10.33.2 --activate && + pnpm --filter @pokopia/backend dev" + depends_on: + deps: + condition: service_completed_successfully + postgres: + condition: service_healthy + + frontend: + image: node:22-alpine + working_dir: /app + environment: + NODE_ENV: development + PNPM_HOME: /pnpm + HOST: 0.0.0.0 + PORT: 20015 + CHOKIDAR_USEPOLLING: "true" + NUXT_PUBLIC_API_BASE_URL: ${NUXT_PUBLIC_API_BASE_URL:-http://localhost:20016} + NUXT_SERVER_API_BASE_URL: ${NUXT_SERVER_API_BASE_URL:-http://backend:3001} + NUXT_PUBLIC_SITE_URL: ${NUXT_PUBLIC_SITE_URL:-http://localhost:20015} + VITE_API_BASE_URL: ${VITE_API_BASE_URL:-http://localhost:20016} + VITE_SITE_URL: ${VITE_SITE_URL:-http://localhost:20015} + ports: + - "20015:20015" + volumes: + - .:/app + - root_node_modules:/app/node_modules + - backend_node_modules:/app/backend/node_modules + - frontend_node_modules:/app/frontend/node_modules + - pnpm_store:/pnpm/store + command: > + sh -lc "corepack enable && + corepack prepare pnpm@10.33.2 --activate && + pnpm --filter @pokopia/frontend dev" + depends_on: + deps: + condition: service_completed_successfully + backend: + condition: service_started + +volumes: + postgres18_data: + backend_uploads: + root_node_modules: + backend_node_modules: + frontend_node_modules: + pnpm_store: diff --git a/package.json b/package.json index b27d6f3..d1695ee 100644 --- a/package.json +++ b/package.json @@ -2,13 +2,15 @@ "name": "pokopia", "private": true, "type": "module", - "packageManager": "pnpm@10.33.2", + "packageManager": "pnpm@10.33.3+sha512.a19744364a7e248b92657a4ca5973f9354d21caf982579674b1c539f32c7420c47138ad8b1254df07aba9bc782d9b3029e3db34d5dbff974326eb74dac8ff489", "scripts": { "dev": "pnpm --parallel --filter @pokopia/backend --filter @pokopia/frontend dev", "lint": "pnpm -r lint", "typecheck": "pnpm -r typecheck", "test": "pnpm -r test", - "build": "pnpm -r build" + "build": "pnpm -r build", + "docker:debug": "docker compose -f docker-compose.debug.yml up --build", + "docker:prod": "docker compose up --build" }, "engines": { "node": ">=22"