K12Study/docs/architecture/base-services.md

基础服务配置方案（PG / Redis / 知识图谱 / 向量库）

1. 目标

• 为 4.13-7.1 研发阶段提供统一、可重复的基础服务底座。
• 与现有 docker/dev-common 与 .devcontainer 方案兼容，减少环境差异。

2. 服务基线

• 必选
  • PostgreSQL：主业务数据存储（多 schema）。
  • Redis：缓存、会话、热点数据。
  • Nacos：配置中心与注册中心（服务化阶段）。
  • NebulaGraph：知识图谱主方案（Neo4j 作为开发备选）。
  • Milvus：向量检索主方案。
• 可选
  • Python AI 服务：统一模型调用、图谱同步、向量写入。

3. 环境变量命名建议

• PostgreSQL
  • K12STUDY_DB_HOST
  • K12STUDY_DB_PORT
  • K12STUDY_DB_NAME
  • K12STUDY_DB_USER
  • K12STUDY_DB_PASSWORD
• Redis
  • K12STUDY_REDIS_HOST
  • K12STUDY_REDIS_PORT
  • K12STUDY_REDIS_PASSWORD
• Nacos
  • K12STUDY_REGISTRY_HOST
  • K12STUDY_REGISTRY_PORT
  • K12STUDY_REGISTRY_GRPC_PORT
  • K12STUDY_REGISTRY_RAFT_PORT
• 知识图谱（Nebula）
  • K12STUDY_GRAPH_HOST
  • K12STUDY_GRAPH_PORT
  • K12STUDY_GRAPH_USER
  • K12STUDY_GRAPH_PASSWORD
• 向量库（Milvus）
  • K12STUDY_VECTOR_HOST
  • K12STUDY_VECTOR_PORT
  • K12STUDY_VECTOR_GRPC_PORT

4. 配置落地建议

• 阶段一（M2）
  • 先以本地单机编排启动，保证联调可用。
• 阶段二（M5-M6）
  • 将图谱/向量配置接入 ai-client 与 python-ai。
• 阶段三（M7-M8）
  • 增加连通性与降级测试（图谱不可用、向量库超时、Redis 抖动）。

5. 健康检查建议

• PostgreSQL：pg_isready
• Redis：redis-cli ping
• NebulaGraph：graphd 端口连接可用
• Milvus：HTTP /healthz
• Python AI：GET /health

6. 与现有目录关系

• 现有公共服务编排：docker/dev-common/docker-compose.public-services.yml
• 本文新增服务编排样例：docs/architecture/service-baseline.compose.yaml