xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: ai 协作文档体系重构与多 ai 仲裁结果落地

Browse Source 
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.设计规格文档
This commit is contained in:
SpecialX
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
infra/port-allocation.md Normal file
View File

@@ -0,0 +1,132 @@
# 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 混淆