# 云服务器、云数据库与 OSS 部署设计 ## 1. 背景说明 管理端后续会部署到云服务器,不是只在本地开发环境运行。因此生产架构必须默认使用: 1. 云服务器承载 Nginx、官网静态文件、管理端静态文件、NestJS API。 2. 云数据库承载 PostgreSQL。 3. OSS 承载图片、视频、模型、PDF、ZIP 等文件。 4. 可选 CDN 加速公开静态资源。 本文档用于约束后续开发和部署,不再按纯本地单机方案设计。 ## 2. 推荐云架构 ```mermaid flowchart TD User["前台用户/管理员"] --> DNS["域名 DNS"] DNS --> Nginx["云服务器 Nginx
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 的边界设计正确,避免后续上线时重构上传、文件路径和数据库连接方式。