# Edu 全局端口分配表

> 版本：1.0
> 日期：2026-07-09
> 维护者：coord（AI 协调者）
> 关联文档：[004 架构影响地图 §1.2](../docs/architecture/004_architecture_impact_map.md)、[full-stack-runbook](../docs/standards/full-stack-runbook.md)
>
> 本文件是 Edu 项目所有服务端口的**唯一源**。任何端口新增/变更必须由 coord 同步更新此文件 + 004 §1.2。

---

## 1. 端口分配原则

1. **不冲突**：同一端口不可被两个服务占用（含开发/生产环境）
2. **段位划分**：
   - `8080-8089`：Go 网关层（api-gateway / push-gateway）
   - `3000-3099`：NestJS BFF + 业务服务（HTTP）
   - `4000-4009`：Next.js 微前端 portal（dev server / 生产端口）
   - `50051-50099`：gRPC 服务端口
   - `9090-9099`：基础设施（Prometheus / Grafana / Alertmanager）
   - `9100-9199`：Exporter（node/mysqld/redis）
3. **dev/prod 一致**：开发与生产环境使用相同端口，避免环境差异
4. **占用即登记**：新增服务必须先在此表登记端口，再写代码

---

## 2. Go 网关层（8080-8089）

| 服务         | HTTP 端口 | gRPC 端口 | 说明                                                                | 阶段  |
| ------------ | --------- | --------- | ------------------------------------------------------------------- | ----- |
| api-gateway  | 8080      | —         | 纯 HTTP 反向代理，不做 HTTP↔gRPC 转换                               | P1 ✅ |
| push-gateway | 8081      | —         | WebSocket + HTTP /internal/*；**coord 仲裁豁免 gRPC**（2026-07-09） | P5    |

> **push-gateway gRPC 豁免说明**：ai-allocation §5 原要求 push-gateway 实现 gRPC PushService。coord 仲裁豁免，理由：(1) push-gateway 是基础设施层无流式推送场景；(2) 现有 HTTP /internal/push 已落地；(3) msg/student-bff 调用方改用 HTTP。50058 端口让给 ai 服务。

---

## 3. NestJS BFF + 业务服务（3000-3099）

| 服务        | HTTP 端口 | gRPC 端口 | 说明                                            | 阶段    |
| ----------- | --------- | --------- | ----------------------------------------------- | ------- |
| iam         | 3002      | 50052     | P2 启用 gRPC server（I1 裁决，2026-07-09 修正） | P2 ✅   |
| teacher-bff | 3003      | —         | BFF 不暴露 gRPC，对下游走 gRPC                  | P2 ✅   |
| core-edu    | 3004      | 50053     | 含原 classes 服务（合并后）                     | P3      |
| content     | 3005      | 50054     | Neo4j + ES                                      | P4      |
| data-ana    | 3006      | 50055     | HTTP 保留作 Gateway 直连降级，gRPC 为 P4 主入口 | P4      |
| msg         | 3007      | 50056     | 通知中心                                        | P5      |
| ai          | 3008      | 50058     | LLM 网关                                        | P5      |
| student-bff | 3009      | —         | BFF 不暴露 gRPC                                 | P3      |
| parent-bff  | 3010      | —         | BFF 不暴露 gRPC                                 | P4      |
| ~~classes~~ | ~~3001~~  | ~~—~~     | 已合并入 core-edu（P3）                         | P1 历史 |

> **端口空闲**：3000、3011-3099 预留扩展。

---

## 4. Next.js 微前端 portal（4000-4009）

| Portal         | dev 端口 | 生产端口 | MF 角色    | 阶段  |
| -------------- | -------- | -------- | ---------- | ----- |
| teacher-portal | 4000     | 4000     | Shell 宿主 | P2 ✅ |
| student-portal | 4001     | 4001     | Remote     | P3    |
| parent-portal  | 4002     | 4002     | Remote     | P4    |
| admin-portal   | 4003     | 4003     | Remote     | P6    |

> **coord 仲裁**（2026-07-09）：
>
> - admin-portal §12.1 表格原写 3003（与 teacher-bff 冲突），统一修正为 **4003**
> - admin-portal MF 配置 `remotes.teacher` 原写 `http://localhost:3000`，修正为 `http://localhost:4000/teacher/remoteEntry.js`
> - 4 端 dev/prod 端口一致，避免环境差异

---

## 5. gRPC 服务端口（50051-50099）

| 服务             | gRPC 端口 | 暴露 Service                                                                      | 阶段          |
| ---------------- | --------- | --------------------------------------------------------------------------------- | ------------- |
| iam              | 50052     | IamService（P2 启用，I1 裁决）                                                    | P2            |
| core-edu         | 50053     | ExamService / HomeworkService / GradeService / AttendanceService / ClassService   | P3            |
| content          | 50054     | TextbookService / ChapterService / KnowledgeGraphService / QuestionService        | P4            |
| data-ana         | 50055     | AnalyticsService                                                                  | P4            |
| msg              | 50056     | NotificationService / NotificationPreferenceService / NotificationTemplateService | P5            |
| ai               | 50058     | AiService                                                                         | P5            |
| ~~push-gateway~~ | ~~50057~~ | ~~PushService~~                                                                   | 豁免（见 §2） |

> **端口空闲**：50051、50057、50059-50099 预留扩展。
> **push-gateway 50057**：原计划预留，因 gRPC 豁免释放。50058 让给 ai 服务。

---

## 6. 基础设施端口（9080-9199）

| 服务             | 端口                                                                        | 说明                                  |
| ---------------- | --------------------------------------------------------------------------- | ------------------------------------- |
| MySQL            | 3306                                                                        | 业务数据库（external）                |
| Redis            | 6379                                                                        | 缓存 + 会话 + Pub/Sub                 |
| Kafka            | 9092（OUTSIDE）/ 29092（INSIDE）                                            | 双监听器                              |
| Kafka UI         | 9000                                                                        | kafka-ui 容器                         |
| Zookeeper        | 2181                                                                        | Kafka 协调                            |
| Debezium Connect | 8083                                                                        | CDC connector                         |
| ClickHouse       | 8123（HTTP）/ 9000（TCP）                                                   | 数据分析宽表                          |
| Neo4j            | 7474（HTTP）/ 7687（Bolt）                                                  | 知识图谱                              |
| Elasticsearch    | 9200（HTTP）/ 9300（TCP）                                                   | 全文检索                              |
| Prometheus       | 9090                                                                        | 指标采集（--web.enable-lifecycle）    |
| Grafana          | 3000（容器内，**与 teacher-bff 3003 不冲突，因 teacher-bff 在 host 网络**） | —                                     | 实际部署需注意 |
| Alertmanager     | 9093                                                                        | 告警                                  |
| Jaeger           | 16686（UI）/ 4317（OTLP gRPC）/ 4318（OTLP HTTP）                           | 链路追踪                              |
| node-exporter    | 9100                                                                        | 主机指标（host.docker.internal:9100） |
| mysqld-exporter  | 9104                                                                        | MySQL 指标                            |
| redis-exporter   | 9121                                                                        | Redis 指标                            |

> **Grafana 端口冲突风险**：Grafana 默认 3000，与 teacher-bff 3003 不冲突（不同主机层），但开发环境若同主机部署需注意。建议 Grafana 改用 3030 避免混淆。

---

## 7. 变更记录

| 日期       | 变更                                                   | 决策者 |
| ---------- | ------------------------------------------------------ | ------ |
| 2026-07-09 | 初始创建，登记全部 15 服务 + 基础设施端口              | coord  |
| 2026-07-09 | 仲裁 admin-portal 3003 → 4003；MF 配置 3000 → 4000     | coord  |
| 2026-07-09 | 仲裁 push-gateway 豁免 gRPC，释放 50057；50058 让给 ai | coord  |
| 2026-07-09 | classes 3001 标记为历史（已合并入 core-edu）           | coord  |

---

## 8. 待办

- [ ] P3 启用前：iam gRPC 50052 / core-edu gRPC 50053 必须落地
- [ ] P4 启用前：content gRPC 50054 / data-ana gRPC 50055 必须落地
- [ ] P5 启用前：msg gRPC 50056 / ai gRPC 50058 必须落地
- [ ] Grafana 端口考虑改为 3030 避免与 teacher-bff 混淆
