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

9.9 KiB
Raw Permalink Blame History

云服务器、云数据库与 OSS 部署设计

1. 背景说明

管理端后续会部署到云服务器,不是只在本地开发环境运行。因此生产架构必须默认使用:

  1. 云服务器承载 Nginx、官网静态文件、管理端静态文件、NestJS API。
  2. 云数据库承载 PostgreSQL。
  3. OSS 承载图片、视频、模型、PDF、ZIP 等文件。
  4. 可选 CDN 加速公开静态资源。

本文档用于约束后续开发和部署,不再按纯本地单机方案设计。

2. 推荐云架构

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 规范

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 上传流程

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 内网地址:

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 后端生产环境变量

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 前端生产环境变量

VITE_API_BASE_URL=/api
VITE_PUBLIC_ASSET_BASE_URL=https://static.example.com

8. Nginx 路由建议

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. 部署流程

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 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。