NewPlatform/docs_old/architecture/technology-stack.md

AIwelink 技术栈选型

状态：第一阶段基线

范围：Web 应用、REST API、数据存储、文件存储、部署和基础监控

说明：Agent 的具体实现方案暂不定型，不在本文件中做最终技术承诺。

1. 总体原则

AIwelink 第一阶段采用模块化、容器化和可渐进扩展的架构：

• 前端与业务 API 分离。
• 对外 API 统一遵循 RESTful 资源设计。
• Web 与 API 通过同一域名提供服务，API 使用 /api/v1 路径反向代理。
• PostgreSQL 作为业务主数据库，使用 JSONB、全文搜索和 pgvector 扩展。
• Redis 用于缓存、限流和异步任务基础设施，不作为最终业务数据源。
• 文件统一存储在阿里云 OSS，数据库只保存文件元数据。
• 应用和任务容器化，第一阶段部署在自有 ECS + Docker Compose，后续按规模迁移到 Kubernetes。
• 用户身份、个人画像、授权和项目行为按数据敏感性分层存储。
• 先采用 Uptime Kuma 做基础可用性监控，后续再升级完整可观测性体系。

2. 已确认技术选型

层	选型
Web 前端	Next.js + React + TypeScript
业务 API	NestJS + Fastify Adapter
API 风格	RESTful API，路径前缀 /api/v1
数据访问	Drizzle ORM 为默认访问工具，复杂查询补充原生 SQL
主数据库	PostgreSQL
向量能力	PostgreSQL pgvector 扩展
缓存与队列基础设施	Redis
文件存储	阿里云 OSS
运行环境	Docker
第一阶段部署	自有 ECS + Docker Compose
后续部署	Kubernetes
身份系统	API 内部 Identity 模块
初期监控	Uptime Kuma

3. 服务边界

浏览器
  │
  ▼
Nginx / 入口反向代理
  ├── /              -> Next.js Web 容器
  └── /api/v1/*      -> NestJS + Fastify API 容器
                                  │
                          Drizzle / SQL Repository
                                  │
                      PostgreSQL + pgvector
                                  │
                                Redis
                                  │
                              阿里云 OSS

Next.js 负责页面和交互，NestJS 负责业务规则和 REST API。浏览器使用同源的 /api/v1/... 路径访问 API，不需要第一阶段建立 API 子域名。

4. 业务模块边界

API 内部按业务模块组织，至少包括：

• Identity：微信登录、邮箱绑定、会话和登录审计。
• Users：基础用户资料、学校、专业和年级。
• Profiles：个人画像、公开画像和画像版本。
• Consents：画像共享授权、撤销和授权审计。
• Projects：竞赛、项目、队伍、成员和申请。
• Invitations：邀请链接、接受记录和邀请关系。
• Points：积分流水、任务和兑换权益。
• Commerce：课程、API 权益、订单和退款记录。
• Recommendations：推荐候选、推荐原因和行为反馈。
• Operations：内容审核、举报、活动和运营配置。

Agent 模块只保留未来可接入的边界，暂不确定模型供应商、编排方式、队列方案和报告生成流程。

5. 数据分层原则

数据按业务含义和敏感性拆分，不提前做多数据库分片：

• 身份数据与联系方式。
• 原始测评回答。
• AI 推测或生成的画像。
• 真实项目行为与合作证据。
• 用户主动公开的画像。
• 授权记录与审计记录。

大型追加型数据先使用独立表、索引和归档策略。只有实际数据量和查询模式证明需要时，再引入 PostgreSQL 分区表或其他专用存储。

6. 文件和媒体

简历、作品、报告和项目附件存储在阿里云 OSS：

1. API 创建临时上传凭证。
2. 浏览器直接上传 OSS。
3. API 接收上传完成通知。
4. PostgreSQL 保存文件元数据和权限关系。
5. 私有文件通过临时签名 URL 访问。

应用服务器不作为大文件长期存储位置。

7. 部署和演进

第一阶段使用 Docker Compose 管理：

• Web 容器。
• API 容器。
• Worker 容器（具体 Agent 方案未定型）。
• PostgreSQL。
• Redis。

生产环境建议将应用容器与 PostgreSQL、Redis 分离到不同主机或使用托管服务，并配置备份和恢复演练。

后续迁移 Kubernetes 时，应用服务应保持无状态，配置通过环境变量或 Secret 注入，文件不写入容器本地磁盘。

8. 监控和测试边界

第一阶段使用 Uptime Kuma 监控：

• 首页可访问性。
• /api/v1/health/live 存活状态。
• /api/v1/health/ready 依赖就绪状态。
• HTTPS 证书和端口状态。

Uptime Kuma 只负责可用性监控，不替代自动化测试。测试工具和覆盖范围另行确定；核心链路至少应覆盖登录、授权、邀请、项目申请和积分流水。

9. 暂不引入

第一阶段暂不引入：

• 微服务拆分。
• Kubernetes。
• 独立向量数据库。
• Elasticsearch / OpenSearch。
• ClickHouse。
• MongoDB。
• 复杂机器学习推荐服务。
• 已定型的 Agent 编排框架。

这些能力在真实规模和业务需求出现后再评估。