Files
mlkj-website-admin/docs/12-cloud-deployment.md
2026-06-29 19:27:33 +08:00

332 lines
9.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 云服务器、云数据库与 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 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。