faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
9.0 KiB
9.0 KiB
Edu 全局端口分配表
版本：1.0 日期：2026-07-09 维护者：coord（AI 协调者） 关联文档：004 架构影响地图 §1.2、full-stack-runbook
本文件是 Edu 项目所有服务端口的唯一源。任何端口新增/变更必须由 coord 同步更新此文件 + 004 §1.2。
1. 端口分配原则
- 不冲突：同一端口不可被两个服务占用（含开发/生产环境）
- 段位划分：
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）
- dev/prod 一致：开发与生产环境使用相同端口，避免环境差异
- 占用即登记：新增服务必须先在此表登记端口，再写代码
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 |
| 已合并入 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 |
| 豁免（见 §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 混淆