Edu/docs/superpowers/specs/2026-07-14-unified-dependency-management-design.md

统一依赖管理设计文档

版本：1.0 日期：2026-07-14 主题：统一 Edu monorepo 多语言依赖管理（Docker 基础镜像 + pnpm + Go + Python + 第三方库） 状态：已批准（等待实施） 关联文档：

• apps/parent-portal/docs/nextstep-v2.md（发现 pnpm 11.x 构建失败、golang:1.22-alpine 无法拉取）
• apps/teacher-portal/nextstep-v2.md
• apps/student-portal/docs/nextstep-v2.md
• apps/admin-portal/docs/nextstep-v2.md
• .trae/rules/project_rules.md §11 多语言 monorepo 规则、§15 CI/CD 规范

---

1. 背景与问题

1.1 问题来源

在核查 4 个前端 portal 的 nextstep-v2.md 时，发现 Docker 构建依赖版本在各个模块间不一致，导致：

1. parent-bff Docker 构建失败：services/parent-bff/Dockerfile 用 npm install -g pnpm（不固定版本）安装了 pnpm 11.x，与 pnpm 9.x 生成的 lockfile 不兼容，触发 ERR_PNPM_IGNORED_BUILDS 错误
2. api-gateway Docker 构建失败：services/api-gateway/Dockerfile 用 golang:1.22-alpine，本地 docker.io 被墙无法拉取，仅有 golang:1.25-alpine
3. admin-portal 版本漂移风险：apps/admin-portal/Dockerfile 用 corepack pnpm@latest（不固定版本），每次构建可能装到不同版本
4. Node 20 与 22 并存：7 个服务用 node:20-alpine，3 个用 node:22-alpine，CI 用 node:22-alpine

1.2 当前依赖版本差异矩阵

Node.js 基础镜像

版本	服务
node:20-alpine	parent-portal、teacher-portal、parent-bff、teacher-bff、iam、content、msg、classes
node:22-alpine	student-portal、admin-portal、student-bff、core-edu、CI quality-ts

pnpm 安装方式（4 种并存）

方式	服务
corepack pnpm@9.12.0（固定）	parent-portal、teacher-portal、student-portal
corepack pnpm@latest（不固定）	admin-portal
npm install -g pnpm（不固定，装最新版 11.x）	parent-bff、teacher-bff、student-bff、iam、core-edu、content、msg、classes
npm install -g pnpm@9（CI）	.github/workflows/ci.yml

Go 基础镜像

版本	服务
golang:1.22-alpine	api-gateway（Dockerfile）、CI quality-go、docker-compose.tools.yml
golang:1.25-alpine	push-gateway（Dockerfile）

Go 模块版本

go.mod	版本
go.work	go 1.25.0
packages/shared-go/go.mod	go 1.22
services/api-gateway/go.mod	go 1.22
services/push-gateway/go.mod	go 1.25.0

TS 服务共享库版本不一致

库	多数服务	异常服务
@grpc/grpc-js	^1.12.0	msg: ^1.11.0
@grpc/proto-loader	^0.7.13	iam: ^0.7.0
kafkajs	^2.2.0	content/parent-bff: ^2.2.4
@nestjs/common	^10.4.0	一致
@nestjs/core	^10.4.0	一致
pino	^9.4.0	一致
prom-client	^15.1.0	一致
graphql-yoga	^5.7.0	一致（仅 BFF 服务用）

1.3 根本原因

1. 历史演进：各服务由不同 AI 独立开发，各自选择 Docker 基础镜像和包管理器安装方式
2. 缺乏统一约束：项目规则 §11 定义了 shared-* 包结构，但未强制规定版本集中声明
3. pnpm 11 安全特性变化：pnpm 11.x 引入 ERR_PNPM_IGNORED_BUILDS，默认拒绝 build scripts，导致旧 Dockerfile 失败
4. 本地镜像源限制：docker.io 被墙，golang:1.22-alpine 无法拉取

---

2. 设计目标

1. 统一 Docker 基础镜像：Node、Go、Python、Alpine 版本全 monorepo 一致
2. 统一 pnpm 安装方式：所有 TS 服务 + 前端 portal + CI 使用同一种固定版本的 pnpm
3. 统一 Go 模块版本：go.work、shared-go、api-gateway、push-gateway 的 go 版本一致
4. 集中声明第三方库：跨服务共享库版本集中到 shared-ts/shared-go/shared-py 包
5. 解决已知阻塞：parent-bff 和 api-gateway 的 Docker 构建失败问题
6. 可重复构建：任何时间、任何环境执行 docker build 都能成功且产物一致

---

3. 设计决策

3.1 决策摘要

决策项	选择	理由
统一范围	全量统一（含第三方库）	彻底解决版本漂移问题
Node 版本	node:22-alpine	CI 已用、3 个服务已验证、Next.js 15+ 推荐、Node 22 LTS 活跃维护
Go 版本	golang:1.25-alpine	go.work 已声明、push-gateway 已用、本地可用、api-gateway 从 1.22 升级兼容
pnpm 版本	pnpm@11.x（通过 corepack 固定）	pnpm 11 是当前活跃版、安全性更高、多个服务已在用。版本号规则：实施时取 npm registry 最新稳定版（如 11.0.0 或更高），在所有 Dockerfile 和 package.json 中使用完全相同的版本号
pnpm 安装方式	corepack enable + prepare	Node 官方推荐、与 package.json packageManager 字段一致
第三方库策略	集中到 shared-* 包	符合项目规则 §11、修改点集中
实施路径	一次性迁移	避免中间态不一致、用户已启用代理可拉取镜像

3.2 pnpm 9 vs 11 的技术分析

pnpm 11 的核心变化

pnpm 11.x 引入 ERR_PNPM_IGNORED_BUILDS 安全特性：默认拒绝运行包的 build scripts（如 @nestjs/core、protobufjs、better-sqlite3 的 postinstall）。这是出于供应链安全考虑。

为什么有些服务用 pnpm 11 "正常运行"

服务	Dockerfile 安装参数	未失败原因
iam	pnpm install --frozen-lockfile	包列表中无 native build scripts 依赖
content	--ignore-scripts	显式跳过 build scripts
msg	--no-frozen-lockfile --ignore-scripts	双重跳过
core-edu	--frozen-lockfile	包列表可能无 native 依赖
teacher-bff	--frozen-lockfile	同上
student-bff	--frozen-lockfile	同上
parent-bff	--frozen-lockfile	失败 — 有 @nestjs/core + protobufjs 需要 build scripts

迁移到 pnpm 11 的必要配置

在根 package.json 添加 pnpm.onlyBuiltDependencies 白名单，允许可信包运行 build scripts：

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "@nestjs/core",
      "protobufjs",
      "better-sqlite3",
      "esbuild",
      "tsx",
      "@swc/core",
    ],
  },
}

---

4. 详细设计

4.1 目标版本矩阵

工具/运行时	当前状态	目标版本	影响范围
Node.js	node:20-alpine(8个) + node:22-alpine(3个)	node:22-alpine	8 个 TS 服务 + 4 个前端 portal + CI quality-ts
pnpm	4 种方式并存	pnpm@11.x（通过 corepack 固定）	所有 TS 服务 + CI + 根 package.json
Go	1.22(拉不到) + 1.25	golang:1.25-alpine	api-gateway + push-gateway + CI quality-go + go.mod
Python	3.12-slim（已一致）	python:3.12-slim（不变）	data-ana + ai
Alpine	3.20（已一致）	alpine:3.20（不变）	api-gateway + push-gateway runner

4.2 根配置层变更

4.2.1 package.json

{
  "name": "next-edu-cloud",
  "engines": {
    "node": ">=22", // 从 >=20 升级
    "pnpm": ">=11", // 从 >=9 升级
  },
  "packageManager": "pnpm@11.x.x", // 实施时取最新稳定版
  "pnpm": {
    "onlyBuiltDependencies": [
      "@nestjs/core",
      "protobufjs",
      "better-sqlite3",
      "esbuild",
      "tsx",
      "@swc/core",
    ],
  },
}

4.2.2 pnpm-lock.yaml 重新生成

# 备份旧 lockfile
mv pnpm-lock.yaml pnpm-lock.yaml.bak-pnpm9

# 安装 pnpm 11
npm install -g pnpm@11

# 重新生成 lockfile
pnpm install

# 验证可重复安装
pnpm install --frozen-lockfile

4.2.3 CI ci.yml 更新

# quality-ts job
quality-ts:
  runs-on: ubuntu-latest
  container: node:22-alpine # 不变（已是 22）
  steps:
    - uses: actions/checkout@v3
    - name: Enable pnpm # 从 npm install -g pnpm@9 改为 corepack
      run: corepack enable && corepack prepare pnpm@11.x.x --activate
    - name: Install dependencies
      run: pnpm install --frozen-lockfile

# quality-go job
quality-go:
  runs-on: ubuntu-latest
  container: golang:1.25-alpine # 从 1.22-alpine 改为 1.25-alpine

4.2.4 docker-compose.tools.yml 更新

name: edu-tools

services:
  # CI 运行时镜像
  node-ci:
    image: node:22-alpine # 不变
  golang-ci:
    image: golang:1.25-alpine # 从 1.22-alpine 改
  buf-ci:
    image: bufbuild/buf:latest # 不变
  docker-ci:
    image: docker:25-git # 不变

  # 服务构建基础镜像
  node-builder:
    image: node:22-alpine # 从 node:20-alpine 改（统一）
  golang-builder:
    image: golang:1.25-alpine # 从 golang:1.22-alpine 改
  alpine-runner:
    image: alpine:3.20 # 不变
  python-builder:
    image: python:3.12-slim # 新增

  # 开发/测试基础设施
  mysql-dev:
    image: mysql:8.0 # 不变
  redis-dev:
    image: redis:7-alpine # 不变

4.3 pnpm 11 迁移方案

4.3.1 所有 TS 服务 + 前端 portal Dockerfile 统一模板

# Build stage
FROM node:22-alpine AS builder
WORKDIR /app

# 统一 pnpm 安装方式（从 4 种 → 1 种）
RUN corepack enable && corepack prepare pnpm@11.x.x --activate

# ... 后续 COPY + pnpm install ...

4.3.2 Dockerfile 变更清单（12 个 TS 项目：8 个 TS 服务 + 4 个前端 portal）

服务	当前方式	目标方式	当前 Node	目标 Node
apps/parent-portal	corepack pnpm@9.12.0	corepack pnpm@11.x.x	20-alpine	22-alpine
apps/teacher-portal	corepack pnpm@9.12.0	corepack pnpm@11.x.x	20-alpine	22-alpine
apps/student-portal	corepack pnpm@9.12.0	corepack pnpm@11.x.x	22-alpine	22-alpine
apps/admin-portal	corepack pnpm@latest	corepack pnpm@11.x.x	22-alpine	22-alpine
services/parent-bff	npm install -g pnpm	corepack pnpm@11.x.x	20-alpine	22-alpine
services/teacher-bff	npm install -g pnpm	corepack pnpm@11.x.x	20-alpine	22-alpine
services/student-bff	npm install -g pnpm	corepack pnpm@11.x.x	22-alpine	22-alpine
services/iam	npm install -g pnpm	corepack pnpm@11.x.x	20-alpine	22-alpine
services/core-edu	npm install -g pnpm	corepack pnpm@11.x.x	22-alpine	22-alpine
services/content	npm install -g pnpm	corepack pnpm@11.x.x	20-alpine	22-alpine
services/msg	npm install -g pnpm	corepack pnpm@11.x.x	20-alpine	22-alpine
services/classes	npm install -g pnpm	corepack pnpm@11.x.x	20-alpine	22-alpine

4.4 Go 版本统一

文件	当前	目标
go.work	go 1.25.0	不变
packages/shared-go/go.mod	go 1.22	go 1.25.0
services/api-gateway/go.mod	go 1.22	go 1.25.0
services/push-gateway/go.mod	go 1.25.0	不变
services/api-gateway/Dockerfile	FROM golang:1.22-alpine	FROM golang:1.25-alpine
services/push-gateway/Dockerfile	FROM golang:1.25-alpine	不变

4.5 第三方库集中到 shared-* 包

4.5.1 shared-ts 集中声明

更新 packages/shared-ts/package.json：

{
  "name": "@edu/shared-ts",
  "dependencies": {
    "@grpc/grpc-js": "^1.12.0", // msg 从 ^1.11.0 升级
    "@grpc/proto-loader": "^0.7.13", // iam 从 ^0.7.0 升级
    "@nestjs/common": "^10.4.0",
    "@nestjs/core": "^10.4.0",
    "graphql-yoga": "^5.7.0",
    "kafkajs": "^2.2.4", // 统一到 ^2.2.4（取最高）
    "pino": "^9.4.0",
    "prom-client": "^15.1.0",
    "@paralleldrive/cuid2": "^2.2.2",
    "drizzle-orm": "^0.31.0",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.0",
  },
}

各服务 package.json 版本对齐规则：各服务保留依赖声明，但版本范围（如 ^1.12.0）必须与 shared-ts 完全一致。即：如果 shared-ts 声明 "@grpc/grpc-js": "^1.12.0"，则所有服务的 @grpc/grpc-js 也必须声明 ^1.12.0，不允许出现 ^1.11.0 等不同范围。

4.5.2 shared-go 集中声明

升级 packages/shared-go/go.mod：

module github.com/edu-cloud/shared-go

go 1.25.0  // 从 go 1.22 升级

require (
    github.com/gin-gonic/gin v1.12.0
    github.com/golang-jwt/jwt/v5 v5.2.1
    github.com/prometheus/client_golang v1.23.2
    go.opentelemetry.io/otel v1.44.0
    go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.44.0
    go.opentelemetry.io/otel/sdk v1.44.0
    go.opentelemetry.io/otel/trace v1.44.0
    go.uber.org/zap v1.27.0
)

api-gateway 和 push-gateway 通过 replace github.com/edu-cloud/shared-go => ../../packages/shared-go 继承。

4.5.3 shared-py 新建

新建 packages/shared-py/pyproject.toml：

[project]
name = "edu-shared-py"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
    "pydantic>=2.9.0",
    "pydantic-settings>=2.5.0",
    "opentelemetry-api>=1.27.0",
    "opentelemetry-sdk>=1.27.0",
    "opentelemetry-exporter-otlp>=1.27.0",
    "opentelemetry-instrumentation-fastapi>=0.48b0",
    "opentelemetry-instrumentation-grpc>=0.48b0",
    "prometheus-client>=0.20.0",
    "structlog>=24.4.0",
    "grpcio>=1.66.0",
    "aiokafka>=0.11.0",
    "redis>=5.0.0",
]

根 pyproject.toml 添加 uv workspace 配置（[tool.uv.workspace]），data-ana 和 ai 通过 workspace 继承。

4.6 不变更项

• Python 3.12-slim（data-ana + ai 已一致）
• Alpine 3.20（api-gateway + push-gateway runner 已一致）
• bufbuild/buf:latest（CI 已用）
• docker:25-git（CI 已用）
• MySQL 8.0 / Redis 7-alpine（基础设施，不在本次范围）

---

5. 实施路径（一次性迁移）

5.1 实施顺序

Step 1: 镜像预拉（用户已启用代理）
  └─ docker compose -f infra/docker-compose.tools.yml pull

Step 2: 根配置层
  ├─ 更新 package.json（packageManager + onlyBuiltDependencies + engines）
  ├─ 删除旧 pnpm-lock.yaml，用 pnpm 11 重新生成
  ├─ 更新 .github/workflows/ci.yml（corepack pnpm@11 + golang:1.25-alpine）
  └─ 更新 infra/docker-compose.tools.yml

Step 3: shared-* 包层
  ├─ 更新 packages/shared-ts/package.json（集中声明第三方库）
  ├─ 更新 packages/shared-go/go.mod（go 1.25.0 + 集中声明）
  └─ 新建 packages/shared-py/pyproject.toml + 根 pyproject.toml uv workspace

Step 4: 各服务层
  ├─ 8 个 TS 服务 Dockerfile: node:22-alpine + corepack pnpm@11.x
  ├─ 4 个前端 portal Dockerfile: node:22-alpine + corepack pnpm@11.x
  ├─ api-gateway: Dockerfile golang:1.25-alpine + go.mod go 1.25.0
  ├─ 各服务 package.json/go.mod/pyproject.toml: 对齐 shared-* 版本
  └─ data-ana + ai: 依赖 shared-py

Step 5: 验证
  └─ 见 §6 验证策略

5.2 文件变更清单

类别	文件	变更类型
根配置	package.json	修改（packageManager + onlyBuiltDependencies + engines）
根配置	pnpm-lock.yaml	删除后重新生成
根配置	.github/workflows/ci.yml	修改（corepack + golang:1.25）
根配置	infra/docker-compose.tools.yml	修改（镜像版本统一）
根配置	pyproject.toml	修改（添加 uv workspace）
shared-*	packages/shared-ts/package.json	修改（集中声明）
shared-*	packages/shared-go/go.mod	修改（go 1.25.0 + 集中声明）
shared-*	packages/shared-py/pyproject.toml	新建
TS 服务	services/{parent-bff,teacher-bff,student-bff,iam,core-edu,content,msg,classes}/Dockerfile	修改（node:22 + corepack pnpm@11）
TS 服务	services/{parent-bff,teacher-bff,student-bff,iam,core-edu,content,msg,classes}/package.json	修改（版本对齐 shared-ts）
前端 portal	apps/{parent-portal,teacher-portal,student-portal,admin-portal}/Dockerfile	修改（node:22 + corepack pnpm@11）
Go 服务	services/api-gateway/Dockerfile	修改（golang:1.25-alpine）
Go 服务	services/api-gateway/go.mod	修改（go 1.25.0）
Python 服务	services/{data-ana,ai}/pyproject.toml	修改（依赖 shared-py）

---

6. 验证策略

6.1 验证层级

Layer 1: 镜像预拉验证
  └─ docker compose -f infra/docker-compose.tools.yml pull（全部成功）

Layer 2: 根配置验证
  ├─ pnpm install（重新生成 lockfile，无 ERR_PNPM_IGNORED_BUILDS）
  └─ pnpm install --frozen-lockfile（可重复安装）

Layer 3: TS 服务验证（8 个服务 + 4 个 portal）
  ├─ pnpm -r run typecheck（零错误）
  ├─ pnpm -r run lint（零错误）
  └─ pnpm -r run build（零错误）

Layer 4: Go 服务验证
  ├─ cd services/api-gateway && go vet ./... && go build ./...（通过）
  └─ cd services/push-gateway && go vet ./... && go build ./...（通过）

Layer 5: Python 服务验证
  ├─ cd services/data-ana && ruff check src/ && uv sync（通过）
  └─ cd services/ai && ruff check src/ && uv sync（通过）

Layer 6: Docker 构建验证（全部 16 个服务）
  ├─ docker build -t edu/parent-bff:test -f services/parent-bff/Dockerfile .（成功）
  ├─ docker build -t edu/api-gateway:test -f services/api-gateway/Dockerfile .（成功）
  └─ ... 其余 14 个服务

Layer 7: 关键服务容器启动验证
  └─ 至少验证 parent-bff（之前失败）+ api-gateway（之前失败）容器可启动且 /healthz 200

6.2 验证 Checklist

• docker-compose.tools.yml 预拉全部成功
• pnpm-lock.yaml 重新生成，无 ERR_PNPM_IGNORED_BUILDS
• pnpm install --frozen-lockfile 可重复
• 8 个 TS 服务 typecheck + lint + build 全通过
• 4 个前端 portal typecheck + lint + build 全通过
• api-gateway go vet + go build 通过（go 1.25）
• push-gateway go vet + go build 通过
• data-ana + ai ruff check + uv sync 通过
• 16 个服务 Docker 镜像构建全部成功
• parent-bff 容器启动 + /healthz 200（之前失败的验证点）
• api-gateway 容器启动 + /healthz 200（之前失败的验证点）

6.3 回滚策略

若验证失败：

1. 保留旧 pnpm-lock.yaml 备份（重命名为 pnpm-lock.yaml.bak-pnpm9）
2. 若 pnpm 11 兼容性问题无法解决，回滚到 pnpm 9.12.0（保留旧 lockfile）
3. 若 Go 1.25 兼容性问题，回滚 api-gateway 到 go 1.22（但需手动解决镜像源问题）

---

7. 风险与缓解

风险	缓解措施
pnpm 11 lockfile 格式变化导致依赖解析差异	重新生成后逐服务 pnpm typecheck + pnpm build 验证
onlyBuiltDependencies 白名单遗漏导致 native 模块缺失	首次 pnpm install 时观察 warning，补充白名单
某些服务可能有 pnpm 9 特有的 lockfile 配置	重新生成后检查 .npmrc 和 pnpm-workspace.yaml 兼容性
corepack 在 Alpine 上的兼容性	已有 3 个 portal 验证 corepack 可用，且 Node 22 内置 corepack
Go 1.22 → 1.25 升级引入不兼容	api-gateway 仅用 gin/jwt/prometheus/opentelemetry，这些库在 Go 1.25 完全兼容
Docker 镜像拉取失败	用户已启用代理，且统一到本地已有镜像版本

---

8. 与项目规则的关系

8.1 符合的规则

• §11 多语言 monorepo 规则：通过 shared-ts/shared-go/shared-py 集中声明第三方库，符合"共享包"设计
• §15 CI/CD 规范：更新 docker-compose.tools.yml 预拉列表，符合 §15.8 镜像预拉规范
• §3.4 TypeScript 规则：corepack 固定版本符合"可重复构建"原则
• §5 契约规范：本次变更不涉及 proto 契约，仅涉及构建工具链

8.2 需要同步的文档

• docs/architecture/004_architecture_impact_map.md：更新依赖版本矩阵章节
• docs/troubleshooting/known-issues.md：记录 pnpm 11 迁移经验（场景→技术映射，不标注 AI 身份）
• apps/*/docs/nextstep-v2.md：更新 Docker 构建相关阻塞项状态

---

9. 成功标准

1. 所有 16 个服务 Docker 镜像构建成功（含之前失败的 parent-bff 和 api-gateway）
2. pnpm install --frozen-lockfile 可重复执行（无 ERR_PNPM_IGNORED_BUILDS）
3. 所有服务 typecheck + lint + build 零错误
4. Docker 基础镜像版本全 monorepo 一致（node:22-alpine + golang:1.25-alpine + python:3.12-slim + alpine:3.20）
5. pnpm 安装方式统一为 corepack pnpm@11.x（无 npm install -g pnpm）
6. 第三方库版本集中声明在 shared- 包（各服务版本与 shared- 一致）

---

本设计文档已获用户批准，下一步进入实施计划阶段（writing-plans）。