332 lines
9.9 KiB
Markdown
332 lines
9.9 KiB
Markdown
# 云服务器、云数据库与 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 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。
|