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.设计规格文档
133 lines
9.0 KiB
Markdown
133 lines
9.0 KiB
Markdown
# 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 混淆
|