81a539b9ab
- Node.js 统一到 node:22-alpine，Go 统一到 golang:1.25-alpine，Python 统一到 python:3.12-slim - pnpm 升级到 11.13.0（corepack），新增 allowBuilds 白名单解决 ERR_PNPM_IGNORED_BUILDS - 新增 packages/shared-py 集中 Python 共享依赖，shared-ts 补充 graphql-yoga/prom-client - api-gateway 修复 go.mod 的 shared-go 依赖 + Dockerfile 改用 repo 根作 context - Python 服务（data-ana/ai）Dockerfile 改用 repo 根作 context + 声明 uv workspace sources - 16 个服务的 Dockerfile + CI + docker-compose.tools.yml 全部对齐版本矩阵 - known-issues.md 沉淀 9 条 pnpm 11 / uv workspace / Go shared-go 迁移经验 - 验证：4 服务完全成功（api-gateway /healthz 200），其余 install 成功（build 失败为预存 TS 错误）
API Gateway
Go (Gin) 实现的 API 网关，所有外部请求的统一入口。
职责
- 路由转发：
/api/v1/<service>/*→ 下游服务（iam / teacher-bff / student-bff / parent-bff / core-edu / content / msg / ai / data-ana） - JWT 鉴权：RS256（IAM 签发，Gateway 通过 JWKS 公钥校验），DevMode 下支持
dev-token旁路 - 请求 ID 注入：生成或透传
X-Request-Id（req-<uuid-v4>格式），全链路追踪 - 限流：基于令牌桶的 per-IP 限流（100 rps，突发 20），超限返回 429 +
GW_RATE_LIMITED - 熔断：基于 gobreaker v2 的下游服务熔断，5xx 错误率 > 50% 触发 OPEN，返回 503 +
GW_CIRCUIT_OPEN - 可观测性：slog 结构化日志 + 7 个业务 metrics + OpenTelemetry tracer（资源属性完整）
- CORS / 安全头 / Recovery：标准化中间件链
中间件链
请求处理顺序（自外向内）：
Request → Recovery → OTel → RequestID → CORS → SecurityHeaders → RequestBodyLimit → RateLimit
→ [api/v1 组] CircuitBreaker → AuthMiddleware(RS256) → Metrics → Proxy → Response
| 中间件 | 文件 | 职责 |
|---|---|---|
| Recovery | internal/middleware/recovery.go |
panic 兜底返回 500 + GW_INTERNAL_ERROR |
| OTel | otelgin.Middleware |
OpenTelemetry 自动埋点 |
| RequestID | internal/middleware/requestid.go |
生成/透传 X-Request-Id（req-<uuid-v4>） |
| CORS | internal/middleware/cors.go |
跨域允许（从 Config 读取白名单） |
| SecurityHeaders | internal/middleware/security.go |
安全响应头 + 请求体限制（413 GW_REQUEST_TOO_LARGE） |
| RateLimit | internal/middleware/ratelimit.go |
per-IP 令牌桶限流，超限 429 GW_RATE_LIMITED |
| CircuitBreaker | internal/middleware/circuit-breaker.go |
下游 5xx 错误率 > 50% 触发熔断，503 GW_CIRCUIT_OPEN |
| Auth | internal/middleware/auth.go |
JWT RS256 校验（JWKS），注入 x-user-id/x-user-roles/x-data-scope |
| Metrics | internal/observability/metrics.go |
HTTP 请求计数 + 延迟统计（7 个业务指标） |
路由表
| 前缀 | 目标服务 | 端口 | 鉴权 |
|---|---|---|---|
/api/v1/iam/* |
iam | 3002 | JWT（register/login/refresh 白名单） |
/api/v1/teacher/* |
teacher-bff | 3003 | JWT |
/api/v1/student/* |
student-bff | 3009 | JWT |
/api/v1/parent/* |
parent-bff | 3010 | JWT |
/api/v1/classes/* |
core-edu | 3004 | JWT |
/api/v1/exams/* |
core-edu | 3004 | JWT |
/api/v1/homework/* |
core-edu | 3004 | JWT |
/api/v1/grades/* |
core-edu | 3004 | JWT |
/api/v1/textbooks/* |
content | 3005 | JWT |
/api/v1/chapters/* |
content | 3005 | JWT |
/api/v1/knowledge-points/* |
content | 3005 | JWT |
/api/v1/questions/* |
content | 3005 | JWT |
/api/v1/notifications/* |
msg | 3007 | JWT |
/api/v1/messages/* |
msg | 3007 | JWT |
/api/v1/ai/* |
ai | 3008 | JWT |
/api/v1/analytics/* |
data-ana | 3006 | JWT |
/api/v1/dashboard/* |
data-ana | 3006 | JWT |
健康检查
| 端点 | 用途 | 鉴权 |
|---|---|---|
GET /healthz |
存活探针（liveness） | 无 |
GET /readyz |
就绪探针（readiness，并行 ping 下游 /healthz，软失败规则） | 无 |
GET /metrics |
Prometheus 指标端点（7 个业务指标 + Go runtime） | 无 |
开发
cd services/api-gateway
go run main.go
DevMode（接受 Bearer dev-token 旁路鉴权）：
DEV_MODE=true go run main.go
测试
cd services/api-gateway
go test ./internal/middleware/... -v -cover
构建
go build ./...
docker build -t edu/api-gateway .
配置
通过环境变量配置（见 internal/config/config.go）：
| 变量 | 默认值 | 说明 |
|---|---|---|
API_GATEWAY_PORT |
8080 | 监听端口 |
ENV |
development | 部署环境（production 时 W7 防护生效） |
DEV_MODE |
false | 开发模式旁路：true 时接受 Bearer dev-token（仅非生产） |
IAM_JWKS_URL |
http://localhost:3002/.well-known/jwks.json | RS256 公钥端点（非 DevMode 必填） |
JWT_ISSUER |
next-edu-cloud | JWT 签发者校验 |
JWT_AUDIENCE |
next-edu-cloud | JWT 受众校验 |
CORS_ORIGINS |
（空，用开发默认白名单） | CORS 白名单（逗号分隔） |
CLASSES_SERVICE_URL |
http://localhost:3001 | classes 服务地址（遗留，路由实际走 core-edu） |
IAM_SERVICE_URL |
http://localhost:3002 | iam 服务地址 |
TEACHER_BFF_URL |
http://localhost:3003 | teacher-bff 服务地址 |
STUDENT_BFF_URL |
http://localhost:3009 | student-bff 服务地址 |
PARENT_BFF_URL |
http://localhost:3010 | parent-bff 服务地址 |
CORE_EDU_SERVICE_URL |
http://localhost:3004 | core-edu 服务地址 |
CONTENT_SERVICE_URL |
http://localhost:3005 | content 服务地址 |
DATA_ANA_SERVICE_URL |
http://localhost:3006 | data-ana 服务地址 |
MSG_SERVICE_URL |
http://localhost:3007 | msg 服务地址 |
AI_SERVICE_URL |
http://localhost:3008 | ai 服务地址 |
OTEL_EXPORTER_OTLP_ENDPOINT |
http://localhost:4318 | OpenTelemetry OTLP 端点 |
LOG_LEVEL |
info | 日志级别 |
生产环境警告：
DEV_MODE=true且ENV=production时服务 panic 拒绝启动（W7 防护）。