feat:系统框架

This commit is contained in:
wlx committed 2026-06-29 19:27:33 +08:00
commit c1f1b39e81
25 files changed
+7515

No files matched your search

+331
View File
@@ -0,0 +1,331 @@
# 云服务器、云数据库与 OSS 部署设计
## 1. 背景说明
管理端后续会部署到云服务器,不是只在本地开发环境运行。因此生产架构必须默认使用:
1. 云服务器承载 Nginx、官网静态文件、管理端静态文件、NestJS API。
2. 云数据库承载 PostgreSQL。
3. OSS 承载图片、视频、模型、PDF、ZIP 等文件。
4. 可选 CDN 加速公开静态资源。
本文档用于约束后续开发和部署,不再按纯本地单机方案设计。
## 2. 推荐云架构
```mermaid
flowchart TD
User["前台用户/管理员"] --> DNS["域名 DNS"]
DNS --> Nginx["云服务器 Nginx<br/>HTTPS 80/443"]
Nginx --> SiteStatic["官网静态文件"]
Nginx --> AdminStatic["管理端静态文件 /admin"]
Nginx --> API["NestJS API /api"]
API --> RDS[("云数据库 PostgreSQL")]
API --> OSS["阿里云 OSS"]
API --> Log["应用日志"]
AdminStatic --> OSSUpload["浏览器直传 OSS"]
OSSUpload --> OSS
SiteStatic --> CDN["CDN/OSS 公网访问域名"]
CDN --> OSS
```
## 3. 云资源规划
### 3.1 云服务器
| 项目 | 建议 |
| --- | --- |
| 类型 | 阿里云 ECS 或轻量应用服务器 |
| CPU/内存 | 测试期 2C4G,正式运营建议 2C4G 起 |
| 系统 | Ubuntu 22.04 LTS 或 Alibaba Cloud Linux |
| 运行服务 | Nginx、Node.js/NestJS API、静态文件 |
| 开放端口 | 80、443、必要时开放 SSH 22 |
| 不开放端口 | PostgreSQL、NestJS 内部端口、Redis 内部端口 |
### 3.2 云数据库 PostgreSQL
| 项目 | 建议 |
| --- | --- |
| 类型 | 阿里云 RDS PostgreSQL |
| 版本 | PostgreSQL 14+ |
| 网络 | 与云服务器同地域,优先同 VPC |
| 访问 | 只允许云服务器内网 IP 或安全组访问 |
| 备份 | 开启自动备份,保留至少 7 天 |
| 高可用 | 正式运营建议开启高可用版 |
| 字符集 | UTF-8 |
| 时区 | 统一使用 UTC 存储,前端按本地展示 |
### 3.3 OSS
| 项目 | 建议 |
| --- | --- |
| Bucket | 单独创建官网管理端 bucket |
| 地域 | 与云服务器、RDS 尽量同地域 |
| 权限 | 默认私有,公开展示资源通过 CDN 或受控公开 URL |
| 上传 | 管理端使用临时凭证或 Post Policy 直传 |
| 目录 | 按业务场景和用途分目录 |
| 生命周期 | 未绑定临时文件可定期清理 |
| 防盗链 | 正式上线建议配置 Referer 白名单 |
### 3.4 CDN
CDN 可选,但正式对外展示建议接入:
| 资源 | 是否建议 CDN |
| --- | --- |
| 官网图片 | 建议 |
| 赛道页图片 | 建议 |
| 课程封面 | 建议 |
| 大视频 | 建议,视频量大后升级 VOD |
| 作品模型 | 按访问量决定 |
| 评审内部附件 | 不建议公开 CDN,使用签名 URL |
## 4. 网络与安全组
### 4.1 访问边界
| 服务 | 访问来源 | 端口 | 说明 |
| --- | --- | --- | --- |
| Nginx | 公网 | 80/443 | 对外访问官网、管理端、API |
| SSH | 管理员固定 IP | 22 | 建议限制来源 IP |
| NestJS API | Nginx 本机反代 | 3001 或内部端口 | 不直接公网开放 |
| PostgreSQL RDS | 云服务器内网 IP | 5432 | 禁止公网全开放 |
| OSS | 浏览器和 API | HTTPS | 通过临时凭证和权限策略控制 |
### 4.2 安全要求
1. RDS 白名单只配置云服务器内网 IP 或安全组。
2. OSS AccessKey 只存在服务器环境变量中,不传给浏览器。
3. 管理端上传使用短期有效凭证。
4. Nginx 强制 HTTPS。
5. 管理端后台路径建议使用 `/admin`,API 使用 `/api`。
6. 后端内部端口不得暴露到公网。
## 5. OSS 文件策略
### 5.1 Bucket 权限策略
建议默认使用私有 bucket,并按资源类型决定访问方式。
| 资源类型 | 访问方式 |
| --- | --- |
| 官网公开图片 | CDN 或公开读 URL |
| 赛道页公开图片 | CDN 或公开读 URL |
| 课程公开视频 | CDN/OSS URL,播放量大后改 VOD |
| 作品公开封面/图集 | CDN 或公开读 URL |
| 作品模型 | 可公开展示的模型使用公开 URL,评审原始文件使用签名 URL |
| 评审附件 | 私有,后端鉴权后生成短期签名 URL |
| 管理端临时上传 | 私有,完成后登记并绑定业务 |
### 5.2 OSS Key 规范
```text
mlkj-website/
site/
images/{yyyy}/{mm}/{hash}.{ext}
competition/
images/{yyyy}/{mm}/{hash}.{ext}
resources/{yyyy}/{mm}/{hash}.{ext}
courses/
covers/{yyyy}/{mm}/{hash}.{ext}
videos/{yyyy}/{mm}/{hash}.{ext}
works/
covers/{yyyy}/{mm}/{hash}.{ext}
images/{yyyy}/{mm}/{hash}.{ext}
models/{yyyy}/{mm}/{hash}.{ext}
documents/{yyyy}/{mm}/{hash}.{ext}
tmp/
uploads/{yyyy}/{mm}/{hash}.{ext}
```
### 5.3 上传流程
```mermaid
sequenceDiagram
participant Admin as 管理端
participant API as 云服务器 API
participant OSS as OSS
participant DB as 云数据库
Admin->>API: POST /api/admin/uploads/policy
API->>API: 校验登录、权限、文件类型、大小
API-->>Admin: 返回短期上传凭证、fileKey
Admin->>OSS: 直传文件
OSS-->>Admin: 上传成功
Admin->>API: POST /api/admin/uploads/complete
API->>DB: 写入 files 和 file_bindings
API-->>Admin: 返回文件记录
```
## 6. 云数据库设计要求
### 6.1 连接方式
生产环境后端使用 RDS 内网地址:
```text
DATABASE_URL=postgresql://user:password@rds-internal-host:5432/mlkj_website?schema=public
```
要求:
1. 不在前端项目中出现数据库连接串。
2. 不在代码中硬编码数据库账号密码。
3. 生产数据库账号按最小权限创建。
4. Migration 只在部署流程中执行,不由普通请求触发。
### 6.2 连接池
| 项目 | 建议 |
| --- | --- |
| API 单实例 | Prisma 默认连接池可先使用 |
| 多实例部署 | 控制连接数,避免打满 RDS |
| 高并发 | 考虑 PgBouncer 或 RDS 连接池能力 |
### 6.3 备份与恢复
1. RDS 自动备份至少保留 7 天。
2. 每次上线 migration 前手动创建快照。
3. 评选开始前和结果发布前建议额外备份。
4. 重要内容发布保留 `content_revisions`,支持业务层回滚。
## 7. 环境变量
### 7.1 后端生产环境变量
```text
NODE_ENV=production
PORT=3001
DATABASE_URL=postgresql://...
JWT_ACCESS_SECRET=...
JWT_REFRESH_SECRET=...
JWT_ACCESS_EXPIRES_IN=2h
JWT_REFRESH_EXPIRES_IN=14d
ADMIN_INITIAL_USERNAME=admin
ADMIN_INITIAL_PASSWORD=change-me-before-production
OSS_REGION=oss-cn-beijing
OSS_BUCKET=mlkj-website-prod
OSS_ACCESS_KEY_ID=...
OSS_ACCESS_KEY_SECRET=...
OSS_PUBLIC_BASE_URL=https://static.example.com
OSS_INTERNAL_ENDPOINT=...
OSS_PUBLIC_ENDPOINT=...
UPLOAD_MAX_IMAGE_SIZE=10485760
UPLOAD_MAX_VIDEO_SIZE=524288000
UPLOAD_MAX_MODEL_SIZE=209715200
UPLOAD_MAX_DOCUMENT_SIZE=52428800
PUBLIC_SITE_ORIGIN=https://www.example.com
ADMIN_SITE_ORIGIN=https://www.example.com/admin
```
### 7.2 前端生产环境变量
```text
VITE_API_BASE_URL=/api
VITE_PUBLIC_ASSET_BASE_URL=https://static.example.com
```
## 8. Nginx 路由建议
```text
https://www.example.com/ -> 官网前台静态文件
https://www.example.com/competition.html -> 赛道页
https://www.example.com/admin/ -> 管理端静态文件
https://www.example.com/api/ -> NestJS API 反向代理
https://www.example.com/api-docs -> Swagger,可按环境限制访问
```
生产建议:
1. `/api-docs` 可仅允许白名单 IP 或加基础鉴权。
2. `/admin` 必须走 HTTPS。
3. 上传大文件时需要调整 Nginx 超时,但直传 OSS 后压力会小很多。
## 9. 部署流程
```mermaid
flowchart TD
A["准备云资源"] --> B["配置 RDS、OSS、安全组"]
B --> C["配置服务器环境变量"]
C --> D["构建后端和前端"]
D --> E["备份数据库"]
E --> F["执行 Prisma migration"]
F --> G["执行 seed 初始化权限和内容"]
G --> H["启动 NestJS API"]
H --> I["部署官网和管理端静态文件"]
I --> J["Nginx reload"]
J --> K["上线验证"]
```
上线验证:
| 项目 | 检查 |
| --- | --- |
| API | `/api/health` 正常 |
| Swagger | 可访问或白名单可访问 |
| 数据库 | 后端能读写 RDS |
| OSS | 管理端能上传文件 |
| CDN/OSS URL | 前台图片可访问 |
| 管理端 | 可登录、上传、发布 |
| 前台 | 已发布内容可展示 |
## 10. 运维要求
### 10.1 日志
| 日志 | 保存位置 |
| --- | --- |
| Nginx access/error | 云服务器 |
| NestJS 应用日志 | 云服务器或日志服务 |
| 操作日志 | PostgreSQL `operation_logs` |
| OSS 访问日志 | OSS 日志功能,可后续开启 |
### 10.2 监控
第一版至少关注:
1. 云服务器 CPU、内存、磁盘。
2. API 进程存活。
3. RDS CPU、连接数、慢查询。
4. OSS 流量和请求错误。
5. 磁盘日志是否过大。
### 10.3 备份
| 对象 | 策略 |
| --- | --- |
| PostgreSQL | RDS 自动备份 + 上线前手动快照 |
| OSS | 开启版本控制或关键目录定期备份 |
| 环境变量 | 安全保存,不进入代码仓库 |
| 静态包 | 保留最近 2-3 个发布包,便于回滚 |
## 11. 开发时需要提前适配的点
1. 文件上传接口从一开始就按 OSS 直传设计,不做本地磁盘上传作为正式方案。
2. 数据库字段和 Prisma migration 按云 PostgreSQL 生产环境设计。
3. 不把图片、视频、模型文件放进服务器项目目录。
4. API 返回文件 URL 时区分公开 URL 和签名 URL。
5. 评审附件、原始模型等敏感文件不能默认公开。
6. 环境变量必须区分 local、staging、production。
7. 所有上线步骤必须可重复执行,避免手工改库。
## 12. 成本与扩展建议
| 阶段 | 建议 |
| --- | --- |
| 初期 | 单台云服务器 + RDS PostgreSQL + OSS |
| 访问量上升 | 增加 CDN,前台静态资源全部走 CDN |
| 视频量上升 | 课程视频迁移到阿里云 VOD |
| 后台用户增多 | 增加 Redis,用于 session、限流、缓存 |
| API 压力上升 | API 多实例部署,前面加负载均衡 |
第一版不要过度复杂,但必须把云数据库和 OSS 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。