Edu/docs/standards/local-dev-runbook.md

本地启动手册（Local Dev Runbook）

版本：1.0 日期：2026-07-08 适用范围：Edu 微服务（P1 阶段：api-gateway + classes + teacher-portal） 关联文档：project_rules、004 架构影响地图、known-issues

---

1. 环境依赖

工具	版本要求	验证命令	说明
Node.js	≥ 20	node -v	LTS 版本
pnpm	≥ 9	pnpm -v	corepack enable 自动启用
Go	1.22+	go version	api-gateway 编译
Docker	24+	docker version	基础设施容器化
Docker Compose	v2+	docker compose version	编排基础设施
Git	2.30+	git --version	husky hooks 需要

Windows 用户：建议在 PowerShell 或 Git Bash 中执行。Go 工具链若不在 PATH，临时加入：$env:Path = "C:\Program Files\Go\bin;" + $env:Path

---

2. 服务端口分配

服务	端口	语言/框架	启动方式	健康检查
MySQL	3306	Docker	docker compose up	mysqladmin ping
Redis	6379	Docker	docker compose up	redis-cli ping
api-gateway	8080	Go (Gin)	go run main.go	GET /healthz
classes	3001	NestJS (TS)	pnpm dev	GET /healthz
teacher-portal	3000	Next.js (TS)	pnpm dev	GET /
iam	3002	NestJS	P2 阶段	—
teacher-bff	3003	NestJS	P2 阶段	—

端口冲突排查：netstat -ano \| findstr :8080（Windows）

---

3. 本地开发模式（DEV_MODE）

3.1 首次准备

# 1. 克隆仓库
git clone <repo-url> Edu
cd Edu

# 2. 安装依赖
pnpm install

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，确认：
#   DEV_MODE=true           ← 本地联调用
#   JWT_SECRET=p1-dev-secret-change-in-production
#   DATABASE_URL=mysql://edu:changeme@localhost:3306/next_edu_cloud
#   REDIS_URL=redis://localhost:6379

# 4. 架构扫描（更新 arch.db）
pnpm run arch:scan

3.2 启动基础设施

# 启动 MySQL + Redis（最小基础设施）
docker compose -f infra/docker-compose.minimal.yml up -d

# 验证健康
docker compose -f infra/docker-compose.minimal.yml ps
# 状态应为 healthy

# （可选）国内镜像源加速：infra/docker-compose.minimal.override.yml 已配置 daocloud 镜像

3.3 启动应用服务（三个终端）

终端 1：api-gateway（:8080）

cd services/api-gateway

# Windows：若 Go 不在 PATH，先设置
$env:Path = "C:\Program Files\Go\bin;" + $env:Path

# 设置开发模式环境变量
$env:DEV_MODE="true"
$env:JWT_SECRET="p1-dev-secret-change-in-production"

# 启动
go run main.go

验证：curl http://localhost:8080/healthz → 200 OK

终端 2：classes 服务（:3001）

# 在项目根目录
pnpm --filter @edu/classes-service dev

验证：curl http://localhost:3001/healthz → 200 OK

注：classes 的 HealthModule 需注册到 AppModule，当前若返回 404 见 [known-issues]

终端 3：teacher-portal（:3000）

# 在项目根目录
pnpm --filter @edu/teacher-portal dev

验证：浏览器访问 http://localhost:3000 → 班级管理页面

3.4 一键启动（可选）

# 并行启动所有子包的 dev 脚本（含 api-gateway 需 go run，不会自动启动）
pnpm dev

注：pnpm dev 仅启动 pnpm workspace 内的 TS 服务。api-gateway 是 Go 服务，需单独 go run。

3.5 联调验证

# 1. 直接访问 api-gateway（带 dev-token）
curl -H "Authorization: Bearer dev-token" http://localhost:8080/api/v1/classes
# 预期：200 OK + 班级列表 JSON

# 2. 通过 teacher-portal 代理访问
curl -H "Authorization: Bearer dev-token" http://localhost:3000/api/v1/classes
# 预期：200 OK（经 Next.js rewrites → api-gateway → classes）

# 3. 浏览器访问
# http://localhost:3000 → 班级管理页面，自动加载班级列表

3.6 dev-token 说明

• DEV_MODE=true 时，api-gateway 接受 Authorization: Bearer dev-token
• 注入固定身份：x-user-id: dev-user，x-user-roles: teacher,admin
• 仅限本地联调，生产环境必须 DEV_MODE=false

---

4. 生产模式（Docker Compose）

4.1 构建镜像

# 构建三个应用服务镜像
docker compose -f infra/docker-compose.prod.yml build

4.2 启动完整栈

# 1. 先启动基础设施（MySQL + Redis）
docker compose -f infra/docker-compose.minimal.yml up -d

# 2. 启动应用服务
docker compose -f infra/docker-compose.prod.yml up -d

# 3. 查看状态
docker compose -f infra/docker-compose.prod.yml ps
# 所有服务应为 healthy

# 4. 查看日志
docker compose -f infra/docker-compose.prod.yml logs -f api-gateway

4.3 生产环境配置要点

配置项	生产值	说明
DEV_MODE	false	docker-compose.prod.yml 强制设为 false
JWT_SECRET	强随机值	替换 p1-dev-secret-change-in-production
DATABASE_URL	生产数据库连接	容器内用 host.docker.internal 或 compose 网络
NODE_ENV	production	teacher-portal 启用生产优化
LOG_LEVEL	info 或 warn	生产日志级别

4.4 生产验证

# 健康检查
curl http://localhost:8080/healthz   # api-gateway
curl http://localhost:3001/healthz   # classes
curl http://localhost:3000/          # teacher-portal

# 鉴权验证（生产模式 dev-token 应被拒绝）
curl -H "Authorization: Bearer dev-token" http://localhost:8080/api/v1/classes
# 预期：401 INVALID_TOKEN

# 真实 JWT 访问（需 IAM 签发）
curl -H "Authorization: Bearer <real-jwt>" http://localhost:8080/api/v1/classes
# 预期：200 OK

4.5 停止与清理

# 停止应用服务
docker compose -f infra/docker-compose.prod.yml down

# 停止基础设施
docker compose -f infra/docker-compose.minimal.yml down

# 清理数据卷（谨慎！会删除数据库数据）
docker compose -f infra/docker-compose.minimal.yml down -v

---

5. 单独构建与运行（裸机生产）

5.1 api-gateway

cd services/api-gateway

# 编译
go build -o bin/api-gateway ./main.go

# 运行（生产环境变量）
DEV_MODE=false JWT_SECRET=<your-secret> ./bin/api-gateway

5.2 classes 服务

# 构建
pnpm --filter @edu/classes-service build

# 运行（从 dist/ 启动）
NODE_ENV=production PORT=3001 \
  DATABASE_URL=mysql://edu:changeme@localhost:3306/next_edu_cloud \
  REDIS_URL=redis://localhost:6379 \
  node services/classes/dist/main.js

5.3 teacher-portal

# 构建
pnpm --filter @edu/teacher-portal build

# 运行
NODE_ENV=production PORT=3000 \
  API_GATEWAY_URL=http://localhost:8080 \
  node apps/teacher-portal/node_modules/.bin/next start -p 3000

---

6. 常见问题

6.1 ERR_TOO_MANY_REDIRECTS

症状：浏览器访问 :3000/api/v1/classes 无限重定向。

根因：Gin 默认 RedirectTrailingSlash=true，/classes → 301 → /classes/，Next.js rewrites 代理形成循环。

修复：main.go 已设 r.RedirectTrailingSlash = false，并同时注册无尾斜杠与通配符路由。

6.2 Docker Hub 拉取超时

症状：docker compose up 时 MySQL/Redis 镜像拉取超时。

修复：infra/docker-compose.minimal.override.yml 已配置 daocloud 镜像源，docker compose 会自动加载。

6.3 classes DI 注入失败

症状：TypeError: Cannot read properties of undefined (reading 'create')。

根因：NestJS ESM 模式下 emitDecoratorMetadata 不工作。

修复：ClassesService 构造函数已加 @Inject(ClassesRepository) 显式指定 token。

6.4 ESM import 缺 .js 后缀

症状：error TS2307: Cannot find module './health.controller'。

修复：ESM 模式下相对 import 必须带 .js 后缀（详见 project_rules §3.4）。

6.5 JWT 401 INVALID_TOKEN

症状：带 dev-token 仍返回 401。

排查：

1. 确认 DEV_MODE=true 环境变量已设置（api-gateway 进程）
2. 确认请求头格式：Authorization: Bearer dev-token（注意 Bearer 后空格）
3. 生产模式（DEV_MODE=false）下 dev-token 被拒绝是预期行为

6.6 Go 工具链不在 PATH

症状：Git Bash 或 PowerShell 中 go: command not found。

修复：

$env:Path = "C:\Program Files\Go\bin;" + $env:Path

---

7. 数据库初始化

classes 服务使用 Drizzle ORM，首次运行需建表：

# 生成迁移
pnpm --filter @edu/classes-service drizzle-kit generate

# 执行迁移
pnpm --filter @edu/classes-service drizzle-kit migrate

若 drizzle-kit 未配置，可手动执行 services/classes/src/db/schema.sql（如存在）。

---

8. 相关文档

• 项目规则 — 强制约束
• 004 架构影响地图 — 服务清单与调用关系
• known-issues — 已知问题速查
• Git 工作流 — 提交与 PR 规范
• 多 AI 协作指南 — 多 Agent 并行开发流程