Edu/docs/runbooks/local-stack.md

# 本地全栈启动运维手册

> 版本：v2.1（混合部署模式）
> 日期：2026-07-17
> 适用范围：Edu v2.1 架构本地开发与测试环境

---

## 1. 架构概览

### 1.1 部署模式

**混合部署**：基础设施 + Apollo Router 用 Docker，应用服务本地运行。

| 层级          | 运行方式       | 说明                                                            |
| ------------- | -------------- | --------------------------------------------------------------- |
| 基础设施      | Docker Compose | MySQL/Redis/Kafka/ClickHouse/Neo4j/ES 等                        |
| Apollo Router | Docker 容器    | 联邦 GraphQL 网关（组合 5 个子图，端口 3000）                   |
| 应用服务      | 本地进程       | NestJS（pnpm exec nest start）/ Python（uvicorn）/ Go（go run） |
| 前端          | 本地进程       | Next.js dev server（portal-shell）                              |

> Apollo Router 在 Docker 容器中运行，通过 `host.docker.internal` 访问 host 上的 5 个 Federation 2 子图（iam/core-edu/content/msg/config-service），compose 出 supergraph 后对外暴露 `http://localhost:3000/graphql`。

### 1.2 服务端口映射

#### 基础设施（Docker）

| 服务          | 端口      | 容器名            |
| ------------- | --------- | ----------------- |
| MySQL         | 3306      | edu-mysql         |
| Redis         | 6379      | edu-redis         |
| Kafka         | 9092      | edu-kafka         |
| Zookeeper     | 2181      | edu-zookeeper     |
| ClickHouse    | 8123      | edu-clickhouse    |
| Neo4j         | 7474/7687 | edu-neo4j         |
| Elasticsearch | 9200      | edu-es            |
| Debezium      | 8083      | edu-debezium      |
| Apollo Router | 3000/8088 | edu-apollo-router |
| Jaeger        | 16686     | edu-jaeger        |
| Prometheus    | 9090      | edu-prometheus    |
| Grafana       | 3030      | edu-grafana       |
| Alertmanager  | 9093      | edu-alertmanager  |
| Loki          | 3100      | edu-loki          |

#### 应用服务（本地）

| 服务           | 端口 | gRPC 端口 | 类型    | 健康端点    |
| -------------- | ---- | --------- | ------- | ----------- |
| iam            | 3002 | 50052     | NestJS  | /healthz    |
| config-service | 3011 | 50059     | NestJS  | /healthz    |
| classes        | 3001 | 50053     | NestJS  | /healthz    |
| core-edu       | 3004 | 50054     | NestJS  | /healthz    |
| content        | 3005 | 50055     | NestJS  | /healthz    |
| msg            | 3007 | 50056     | NestJS  | /healthz    |
| data-ana       | 3006 | -         | Python  | /healthz    |
| ai             | 3008 | -         | Python  | /healthz    |
| api-gateway    | 8080 | -         | Go      | /healthz    |
| push-gateway   | 8081 | -         | Go      | /healthz    |
| portal-shell   | 4010 | -         | Next.js | /api/health |

---

## 2. 一键脚本使用

### 2.1 一键启动

```powershell
# 启动全部（基础设施 + 应用服务 + Apollo Router）
.\scripts\start-all.ps1

# 仅启动基础设施
.\scripts\start-all.ps1 -SkipApps

# 仅启动应用服务（基础设施已运行）
.\scripts\start-all.ps1 -SkipInfra

# 自动杀掉占用端口的进程（不交互确认）
.\scripts\start-all.ps1 -Force

# 跳过 Apollo Router（仅用 config-service 直连，调试子图时使用）
.\scripts\start-all.ps1 -SkipRouter
```

**启动流程**（8 阶段）：

1. 加载 `.env` 文件
2. 启动 Docker 基础设施（p3+p5 profile + observability）
3. 基础设施健康检查
4. 端口冲突检查与清理
5. 确保 `@edu/shared-ts` 已编译
6. 清理 NestJS tsbuildinfo 缓存
7. 启动应用服务 + 健康检查
8. 启动 Apollo Router（Docker 容器，组合 5 子图 supergraph）

> Apollo Router 依赖 5 个 Federation 2 子图（iam/core-edu/content/msg/config-service）就绪后才能 compose supergraph，因此在第 7 步应用服务健康检查通过后才启动。如果跳过 `-SkipRouter`，portal-shell 会自动降级到 config-service 直连（http://localhost:3011）。

### 2.2 一键关闭

```powershell
# 关闭应用服务 + Apollo Router
.\scripts\stop-all.ps1

# 强制按端口杀进程（窗口关闭后进程残留时使用）
.\scripts\stop-all.ps1 -KillByPort

# 关闭应用 + Apollo Router + Docker 基础设施
.\scripts\stop-all.ps1 -IncludeDocker

# 全部关闭
.\scripts\stop-all.ps1 -KillByPort -IncludeDocker

# 仅关闭应用，保留 Router 容器
.\scripts\stop-all.ps1 -SkipRouter
```

> 关闭顺序：Apollo Router 容器 → 应用服务窗口 → 按端口杀残留 → Docker 基础设施。先关 Router 避免子图关闭时 router 刷连接错误日志。

### 2.3 典型工作流

```powershell
# 早晨开始工作：一键启动
.\scripts\start-all.ps1

# 中午休息：仅关闭应用（保留 Docker 数据）
.\scripts\stop-all.ps1 -KillByPort

# 下午继续：仅启动应用
.\scripts\start-all.ps1 -SkipInfra -Force

# 下班：全部关闭
.\scripts\stop-all.ps1 -KillByPort -IncludeDocker
```

---

## 3. 手动操作

### 3.1 仅启动基础设施

```powershell
cd infra
# 基础设施服务（跳过需构建镜像的 app 服务）
docker compose -f docker-compose.yml --profile p3 --profile p5 up -d mysql redis kafka zookeeper clickhouse neo4j elasticsearch debezium-connect
# 可观测性栈
docker compose -f docker-compose.yml --profile observability up -d
```

### 3.2 单独启动某个应用服务

```powershell
# NestJS 服务
pnpm --filter @edu/iam-service exec nest start
pnpm --filter @edu/config-service exec nest start
pnpm --filter @edu/classes-service exec nest start
pnpm --filter @edu/core-edu-service exec nest start
pnpm --filter @edu/content-service exec nest start
pnpm --filter @edu/msg-service exec nest start

# Python 服务
cd services\data-ana; uv run uvicorn data_ana.main:app --app-dir src --host 0.0.0.0 --port 3006
cd services\ai; uv run uvicorn ai.main:app --app-dir src --host 0.0.0.0 --port 3008

# Go 服务
cd services\api-gateway; go run .
cd services\push-gateway; go run .

# 前端
pnpm --filter @edu/portal-shell dev
```

### 3.3 健康检查

```powershell
# 单个服务
curl http://localhost:3002/healthz   # iam
curl http://localhost:4010/api/health # portal-shell

# 批量健康检查脚本
.\scripts\health-check.ps1
```

### 3.4 查看 Docker 容器状态

```powershell
# 运行中的容器
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 查看容器日志
docker logs edu-mysql --tail 50
docker logs edu-kafka --tail 50 -f

# 容器健康状态
docker inspect -f '{{.State.Health.Status}}' edu-mysql
```

### 3.5 手动启动 Apollo Router

Apollo Router 通常由 `start-all.ps1` 自动启动。如需单独启动（例如调试 router 配置）：

```powershell
# 前置：5 个 Federation 2 子图必须先在 host 上运行
#   iam (3002) / core-edu (3004) / content (3005) / msg (3007) / config-service (3011)
# 验证子图：rover subgraph introspect http://localhost:3002/graphql
#   返回应包含 @key、@link、_service 字段

# 启动 Router 容器（dev 模式，子图在 host 上）
docker rm -f edu-apollo-router 2>&1 | Out-Null
docker run -d --name edu-apollo-router `
    --add-host=host.docker.internal:host-gateway `
    -p 3000:3000 -p 8088:8088 `
    -v e:\Desktop\Edu\infra\apollo-router\dev-supergraph.yaml:/dist/supergraph.yaml `
    -v e:\Desktop\Edu\infra\apollo-router\dev-entrypoint.sh:/dist/entrypoint.sh `
    -v e:\Desktop\Edu\infra\apollo-router\router.yaml:/dist/configuration.yaml `
    -e ROUTER_AUTH_SECRET=dev-router-secret `
    -e APOLLO_ELV2_LICENSE=accept `
    -e HTTP_PROXY=http://host.docker.internal:7897 `
    -e HTTPS_PROXY=http://host.docker.internal:7897 `
    -e NO_PROXY=localhost,127.0.0.1,host.docker.internal `
    edu/apollo-router:dev `
    /dist/entrypoint.sh

# 验证
curl http://localhost:8088/health            # {"status":"UP"}
curl -X POST http://localhost:3000/graphql `
    -H "Content-Type: application/json" `
    -d '{\"query\":\"{ __schema { queryType { fields { name } } } }\"}'

# 查看日志（supergraph compose 过程 + router 启动）
docker logs edu-apollo-router -f
```

> 首次启动需 `docker build -t edu/apollo-router:dev infra/apollo-router/` 构建镜像（包含 rover CLI 和预下载的 supergraph 插件）。`HTTP_PROXY` 用于容器内 rover 下载 supergraph 插件（如已预下载到镜像则可省略）。

---

## 4. 环境变量

### 4.1 必需的 .env 变量

根目录 `.env` 文件必须包含以下变量：

```env
# 数据库
DATABASE_URL=mysql://edu:changeme@localhost:3306/next_edu_cloud
MYSQL_ROOT_PASSWORD=changeme
MYSQL_DATABASE=next_edu_cloud
MYSQL_USER=edu
MYSQL_PASSWORD=changeme

# Redis
REDIS_URL=redis://localhost:6379

# Kafka
KAFKA_BROKERS=localhost:9092

# JWT 密钥路径
IAM_PRIVATE_KEY_PATH=E:\Desktop\Edu\keys\iam-private.pem
IAM_PUBLIC_KEY_PATH=E:\Desktop\Edu\keys\iam-public.pem

# 开发模式（绕过 JWT 校验，接受 dev-token）
DEV_MODE=true

# Router 认证密钥（子图校验 Apollo Router 请求）
ROUTER_AUTH_SECRET=dev-router-secret

# Neo4j
NEO4J_PASSWORD=changeme

# 可观测性
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```

### 4.2 开发模式（DEV_MODE=true）

- 绕过 JWT 校验
- 接受 `Authorization: Bearer dev-token` 作为有效令牌
- 预定义用户角色

### 4.3 env-loader 机制

NestJS 服务通过 `@edu/shared-ts/env-loader` 在启动时自动从 monorepo 根加载 `.env` 文件，解决 PowerShell → pnpm → nest 子进程环境变量丢失问题。所有 NestJS 服务的 `main.ts` 顶部已添加：

```typescript
import "@edu/shared-ts/env-loader";
```

---

## 5. 前置准备

### 5.1 首次运行

```powershell
# 1. 安装依赖
pnpm install --no-frozen-lockfile

# 2. 编译 shared-ts（其他服务依赖它）
pnpm --filter @edu/shared-ts build

# 3. 生成 JWT 密钥（如不存在）
mkdir keys
openssl genrsa -out keys/iam-private.pem 2048
openssl rsa -in keys/iam-private.pem -pubout -out keys/iam-public.pem

# 4. 配置 .env（从 .env.example 复制并修改）
cp .env.example .env
```

### 5.2 工具链要求

| 工具       | 版本   | 用途                         |
| ---------- | ------ | ---------------------------- |
| Node.js    | 22+    | NestJS / Next.js             |
| pnpm       | 11+    | 包管理                       |
| Go         | 1.22+  | api-gateway / push-gateway   |
| uv         | latest | Python 服务（data-ana / ai） |
| Docker     | 25+    | 基础设施容器                 |
| PowerShell | 7+     | 启动脚本                     |

---

## 6. 访问入口

### 6.1 应用入口

| 入口         | URL                           | 说明                       |
| ------------ | ----------------------------- | -------------------------- |
| Portal Shell | http://localhost:4010         | 统一前端                   |
| API Gateway  | http://localhost:8080         | REST API 网关              |
| IAM GraphQL  | http://localhost:3002/graphql | IAM 子图（需 Router Auth） |

### 6.2 监控入口

| 入口         | URL                    | 登录          |
| ------------ | ---------------------- | ------------- |
| Grafana      | http://localhost:3030  | admin / admin |
| Jaeger       | http://localhost:16686 | 无需登录      |
| Prometheus   | http://localhost:9090  | 无需登录      |
| Alertmanager | http://localhost:9093  | 无需登录      |

### 6.3 基础设施管理

| 服务          | URL / 端口            | 登录               |
| ------------- | --------------------- | ------------------ |
| MySQL         | localhost:3306        | edu / changeme     |
| Redis         | localhost:6379        | 无密码             |
| Neo4j         | http://localhost:7474 | neo4j / changeme   |
| ClickHouse    | http://localhost:8123 | default / (无密码) |
| Elasticsearch | http://localhost:9200 | 无需认证           |

---

## 7. 故障排查

### 7.1 常见问题

| 问题                          | 解决方案                                                                 |
| ----------------------------- | ------------------------------------------------------------------------ |
| 端口被占用                    | `.\scripts\stop-all.ps1 -KillByPort` 或 `start-all.ps1 -Force`           |
| NestJS 环境变量缺失           | 确认 `.env` 存在且 `main.ts` 顶部有 `import "@edu/shared-ts/env-loader"` |
| shared-ts 找不到              | `pnpm --filter @edu/shared-ts build`                                     |
| pnpm install 失败（lockfile） | `pnpm install --no-frozen-lockfile`                                      |
| Docker 容器启动失败           | `docker logs <container>` 查看日志                                       |
| MySQL 连接失败                | 确认 `edu-mysql` 容器 healthy：`docker ps`                               |
| Kafka 连接失败                | 确认用 `localhost:9092`（OUTSIDE listener）                              |
| 前端首页超时                  | Next.js dev 首次编译慢，等待 30 秒后重试                                 |
| GraphQL 子图返回 401          | 子图需 `Router-Authorization` header（ADR-036），非直接访问              |

### 7.2 日志查看

```powershell
# Docker 容器日志
docker logs edu-mysql --tail 100 -f
docker logs edu-kafka --tail 100 -f

# 应用服务日志
# 查看 edu-app-* 命名的 PowerShell 窗口
```

### 7.3 重置环境

```powershell
# 完全重置（删除所有数据）
.\scripts\stop-all.ps1 -KillByPort -IncludeDocker
cd infra
docker compose -f docker-compose.yml --profile p3 --profile p5 --profile observability down -v
cd ..
.\scripts\start-all.ps1
```

### 7.4 Temporal 服务（可选）

Temporal 服务用于 AI 工作流引擎（ADR-030），当前未包含在一键启动脚本中。如需启动：

```powershell
cd infra
docker compose -f docker-compose.yml --profile p3 up -d temporal-postgresql temporal temporal-ui
# 注意：temporal auto-setup 镜像需调整 DB 环境变量为 postgres，当前配置有已知问题
```

---

## 8. 架构约束

> 以下约束来自 project_rules.md 与 ADR，脚本已内置遵守。

- **混合部署**：基础设施 Docker + 应用本地，避免应用镜像构建失败
- **GraphQL 子图隔离**：子图仅接受 Apollo Router 请求（带 `Router-Authorization` header），不直接对外
- **gRPC 内部通信**：服务间通过 gRPC（50052-50059），不通过 GraphQL
- **CDC + Outbox**：业务代码写 outbox 表，Debezium 监听 binlog 投递 Kafka
- **DEV_MODE**：开发模式绕过 JWT 校验，仅限本地开发