diff --git a/.env.example b/.env.example index 6346dbc..1a017ef 100644 --- a/.env.example +++ b/.env.example @@ -1,16 +1,17 @@ # 灵犀 · 环境变量示例（入库，禁止写真实密钥） # 使用：cp .env.example .env.local（工程规范 09 ENV-09） -# 注意：本地 compose 的宿主端口为 15432/16379/19000/19001，避免与本机既有 PG/Redis 冲突。 +# 注意：本地 PostgreSQL/Redis 复用本机已有 Docker 服务（127.0.0.1:5432 / 6379）； +# S3 兼容服务由 infra/docker-compose.dev.yaml 提供（19000/19001）。 # ---------- 运行环境 ---------- NODE_ENV=development LOG_LEVEL=debug # ---------- 数据库（PostgreSQL 18） ---------- -DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:15432/lingxi?schema=public +DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/lingxi?schema=public # ---------- Redis（7.4） ---------- -REDIS_URL=redis://127.0.0.1:16379 +REDIS_URL=redis://127.0.0.1:6379 # ---------- 对象存储（MinIO，S3 协议） ---------- S3_ENDPOINT=http://127.0.0.1:19000 diff --git a/README.md b/README.md index 27a4782..2f21b45 100644 --- a/README.md +++ b/README.md @@ -73,14 +73,14 @@ docs/ PRD / 技术架构 / 开发计划 / 立项建议 / 工程规范 ```bash cp .env.example .env.local cp .env.local .env # Prisma CLI 只读取 .env（两者均已 gitignore） -pnpm compose:up # PostgreSQL 18 / Redis 7.4 / S3 兼容存储 +pnpm compose:up # 启动 S3 兼容存储；PG / Redis 复用本机已有 Docker pnpm db:migrate # 首次建表；后续由 Prisma 迁移管理 pnpm db:seed # 幂等写入 system_configs 基线 pnpm dev # 并行启动 api(3000) / web(5173) / worker ``` -- **本地数据库**：库名 `lingxi`，用户 `postgres`，密码 `postgres`（仅开发环境，见 `infra/docker-compose.dev.yaml` 与 `.env.example`）。 -- **端口**：为避免与本机已有容器冲突，compose 宿主端口为 PostgreSQL `15432`、Redis `16379`、S3 `19000/19001`，容器内仍是 `5432/6379/9000/9001`；`.env.example` 已按宿主端口给出连接串。 +- **本地数据库**：直接复用本机已有 Docker 服务 `docker-postgres-1`（PostgreSQL 18，`127.0.0.1:5432`），库名 `lingxi`，用户 `postgres`，密码 `postgres`；Redis 复用 `docker-redis-1`（`127.0.0.1:6379`）。请先确认这两个容器已启动，本仓库不会另起 PG/Redis。 +- **对象存储端口**：S3 兼容服务由 `pnpm compose:up` 提供，宿主端口 `19000/19001`。 - **对象存储**：当前 Docker 环境拉取不到 `minio/minio` 镜像（registry denied、二进制 410），A0 的 compose 使用 `adobe/s3mock` 并提供 `assets / renders / temp / archive` 四个初始桶；CI 或生产接入真实 MinIO 时只需替换 `infra/docker-compose.dev.yaml` 的 `s3` 服务。 - **API 文档**：启动 api 后访问 `http://127.0.0.1:3000/api/docs`，OpenAPI JSON 在 `openapi/lingxi.openapi.json`。 - **演示登录**：A0 尚未接鉴权（A1 实现），`VITE_PUBLIC_DEMO_SESSION=true` 时登录页使用本地演示会话进入工作台；A1 接入真实登录后删除。 diff --git a/docs/开发计划/灵犀_A0工程骨架与契约基线_实施报告_V0.1.md b/docs/开发计划/灵犀_A0工程骨架与契约基线_实施报告_V0.1.md index 2e92cd2..10b8545 100644 --- a/docs/开发计划/灵犀_A0工程骨架与契约基线_实施报告_V0.1.md +++ b/docs/开发计划/灵犀_A0工程骨架与契约基线_实施报告_V0.1.md @@ -9,7 +9,7 @@ | WBS | 状态 | 落地内容 | | --- | --- | --- | | A0-INF-01 Monorepo / 工具链 | 完成 | pnpm workspace + Turborepo；TS strict、ESLint 9 flat + Prettier + commitlint + lint-staged + husky；`.nvmrc` / `engines` / `packageManager` / preinstall 仅允许 pnpm；目录与 AGENTS.md §5 一致 | -| A0-INF-02 本地依赖与迁移种子 | 完成（种子范围受限，见 §4.4） | `infra/docker-compose.dev.yaml`（PG 18 / Redis 7.4 / S3 兼容服务）+ 健康检查；`.env.example`；Prisma 初始化与首版迁移；`system_configs` 幂等种子 | +| A0-INF-02 本地依赖与迁移种子 | 完成（种子范围受限，见 §4.4） | 复用本机 `docker-postgres-1`（PostgreSQL 18，5432）与 `docker-redis-1`（6379）；`infra/docker-compose.dev.yaml` 仅管理 S3 兼容服务；`.env.example`；Prisma 初始化与首版迁移；`system_configs` 幂等种子 | | A0-INF-03 CI 与质量门禁 | 完成 | `.gitea/workflows/ci.yml`：install → format → lint → typecheck → test → build → migrate → test:int → openapi:export/diff → e2e；新增 `pnpm ci:local` 在无 runner 时本地执行同一门禁；失败阻断 | | A0-BE-01 API 骨架 | 完成 | NestJS 11 + Fastify；Pino + `trace_id`；统一错误体 `{code,message,details,trace_id}`；`GET /health`；`/api/docs` 与 OpenAPI JSON；Zod 管道；CORS / Helmet | | A0-BE-02 Prisma 基线 | 完成 | `PrismaService` 封装；`outbox_events` / `idempotency_keys` / `system_configs`；ULID `char(26)`、软删/时间字段约定；首版迁移可重复执行 | @@ -41,16 +41,16 @@ | `pnpm test:int` | 通过（真实 PostgreSQL + Redis，`/health` 200） | | `pnpm test:e2e` | 通过（4/4，Playwright/Chrome） | | `pnpm openapi:export` + `pnpm openapi:diff` | 通过；快照含 20 个错误码，OpenAPI `3.1.0` | -| `pnpm compose:up` | 通过；`lingxi-pg` / `lingxi-redis` / `lingxi-s3` 均 healthy | +| `pnpm compose:up` | 通过；`lingxi-s3` healthy；PG / Redis 使用本机已运行容器，`/health` 与 `test:int` 验证连通 | | API 启动 | `/health` 200、`/api/docs` 200、`/api/openapi.json` 200 | | Worker 启动 | 连接 Redis 成功，收到 SIGTERM 后正常退出 | | 种子幂等 | 连续执行两次，`system_configs` 保持 7 条 | ## 4. 与文档的差异与待确认 -### 4.1 宿主端口（环境适配） +### 4.1 本地依赖来源（环境适配） -本机已有容器占用 5432 / 6379，A0 compose 宿主端口改为 **15432（PG）/ 16379（Redis）/ 19000–19001（S3）**，容器内端口不变。`.env.example` 已按宿主端口提供连接串；本地数据库为 `lingxi`，用户 `postgres`，密码 `postgres`（仅开发环境）。CI services 使用标准端口，凭据同为 `postgres/postgres`。 +本地 PostgreSQL 与 Redis **复用本机已有 Docker 服务**，不另起容器：`docker-postgres-1`（PostgreSQL 18，`127.0.0.1:5432`，库 `lingxi`、用户 `postgres`、密码 `postgres`）与 `docker-redis-1`（`127.0.0.1:6379`）。`infra/docker-compose.dev.yaml` 仅保留 S3 兼容服务（宿主 `19000/19001`）。CI services 使用标准 5432/6379，凭据同为 `postgres/postgres`。 ### 4.2 对象存储镜像不可得（环境适配） @@ -80,7 +80,7 @@ npm 上 `oasdiff` 为占位包（0.0.1-security），A0 暂用自研 `scripts/op 当前离线 Gitea 未部署 Actions runner，推送后远程 CI 会停留在 `queued`。A0 增加 `pnpm ci:local`：按 `.gitea/workflows/ci.yml` 的顺序在本地执行 compose、格式、Lint、类型、单测、构建、迁移与种子、集成、OpenAPI 契约与 e2e，全部通过才退出 0；runner 就绪后远程工作流可直接接管。 -本地开发数据库已按约定改为：库名 `lingxi`、用户 `postgres`、密码 `postgres`；compose、`.env.example`、CI services 三处保持一致。 +本地开发库为 `lingxi` / `postgres` / `postgres`，直接连接本机已有 PostgreSQL 容器；`.env.example` 与 CI services 保持一致。 ### 4.8 前端视觉方向 diff --git a/infra/docker-compose.dev.yaml b/infra/docker-compose.dev.yaml index 787aac5..2a1ec68 100644 --- a/infra/docker-compose.dev.yaml +++ b/infra/docker-compose.dev.yaml @@ -1,49 +1,14 @@ -# 灵犀 · 本地开发环境编排（PG18 / Redis 7.4 / S3 兼容对象存储） +# 灵犀 · 本地开发对象存储（S3 协议兼容） # 用法：pnpm compose:up / pnpm compose:down -# 说明：本机已有其他 PG/Redis 占用 5432/6379，这里宿主端口统一改用 15432/16379， -# 容器内端口保持标准值；对应 DATABASE_URL / REDIS_URL 见根目录 .env.example。 +# +# 数据库与 Redis 复用本机已有 Docker 服务，不再由本文件创建： +# PostgreSQL → docker-postgres-1，127.0.0.1:5432，库 lingxi / 用户 postgres / 密码 postgres +# Redis → docker-redis-1，127.0.0.1:6379 +# 本文件只管理 S3 兼容服务：2026-11 实测 minio/minio 与 minio/mc 镜像在当前网络不可拉取， +# 本地改用 Adobe S3Mock 提供 assets/renders/temp/archive 四个桶；接入真实 MinIO 时仅替换本服务。 name: lingxi-dev services: - postgres: - image: postgres:18-alpine - container_name: lingxi-pg - environment: - POSTGRES_USER: postgres - POSTGRES_PASSWORD: postgres - POSTGRES_DB: lingxi - TZ: Asia/Shanghai - ports: - - '15432:5432' - volumes: - # PG18+ 镜像要求挂载 /var/lib/postgresql（数据放在版本子目录，便于 pg_upgrade） - - lingxi-pg-data:/var/lib/postgresql - healthcheck: - test: ['CMD-SHELL', 'pg_isready -U postgres -d lingxi'] - interval: 5s - timeout: 3s - retries: 20 - start_period: 10s - - redis: - image: redis:7.4-alpine - container_name: lingxi-redis - command: ['redis-server', '--appendonly', 'yes'] - ports: - - '16379:6379' - volumes: - - lingxi-redis-data:/data - healthcheck: - test: ['CMD', 'redis-cli', 'ping'] - interval: 5s - timeout: 3s - retries: 20 - start_period: 5s - - # 对象存储：技术架构要求 MinIO（S3 协议）。2026-11 实测 minio/minio 与 minio/mc - # 官方镜像在当前网络/仓库均无法拉取（registry denied），quay.io 需鉴权； - # 本地开发改用 S3 兼容的 Adobe S3Mock，接口与四桶（assets/renders/temp/archive）保持一致， - # S3_ENDPOINT 仍指向 19000。CI/生产接入真实 MinIO，切换时仅替换本服务。 s3: image: adobe/s3mock:latest container_name: lingxi-s3 @@ -65,6 +30,4 @@ services: start_period: 20s volumes: - lingxi-pg-data: - lingxi-redis-data: lingxi-s3-data: