143 lines
8.4 KiB
Markdown
143 lines
8.4 KiB
Markdown
## 可移植部署与生产规范（权威版）
|
||
|
||
本指南用于指导将本项目部署到任意公司、任意服务器（含 NAS、低配机）的稳定方案。后续开发与代码评审优先对齐本指南；如有新增需求，在此文档持续补充。
|
||
|
||
### 1. 设计目标
|
||
- 可移植：支持任意服务器或 NAS（x86/ARM，Linux 为主，Windows/WSL 也可）。
|
||
- 稳定与低开销：默认配置适配低性能机器，按需启用昂贵功能。
|
||
- 安全与最小暴露：仅部署必要产物与环境变量；严控日志与资源权限。
|
||
- 可配置：一切可变项均通过环境变量/系统设置控制，避免硬编码。
|
||
- 结构整洁：功能分区清晰，杜绝与业务无关文件进入产线镜像。
|
||
|
||
### 2. 环境与依赖
|
||
- Node 18（推荐容器化运行）。
|
||
- PostgreSQL 14+（容器/外部 RDS 均可）。
|
||
- 反向代理（nginx/caddy/traefik 均可选）。
|
||
- 对象存储（MinIO/S3 兼容端点）。
|
||
|
||
建议使用 Docker Compose 在同机编排 Web 与数据库；受限网络环境请配置镜像源（示例见 `scripts/deploy/setup-docker-mirror.ps1`）。
|
||
|
||
### 3. 目录结构（产线关注）
|
||
- app/…、components/… 前后端源代码（仅保留必要生产构建结果进入镜像）。
|
||
- app/api/… 所有 API 路由（按功能分区）。
|
||
- prisma/schema.prisma 数据模型。生产环境仅执行迁移或确保表结构同步。
|
||
- scripts/deploy/… 部署脚本（客户端执行，不进入产线镜像）。
|
||
- docs/… 文档集合（不进入产线镜像）。
|
||
|
||
生产镜像中不应包含：docs、测试样例、截图、临时脚本、未用到的部署脚本、编辑器配置等。
|
||
|
||
### 4. 环境变量（必须项与推荐项）
|
||
- NEXTAUTH_URL：站点对外访问完整 URL（如 https://portal.example.com）。
|
||
- APP_PUBLIC_URL：邀请链接生成优先使用的公网 URL（强烈推荐设置，避免回落 localhost）。
|
||
- DATABASE_URL：PostgreSQL 连接串。
|
||
- SESSION_SECRET / NEXTAUTH_SECRET：会话密钥（必须为强随机）。
|
||
- S3_ENDPOINT/S3_ACCESS_KEY/S3_SECRET_KEY/S3_BUCKET/S3_REGION/S3_PUBLIC_URL：对象存储配置（启用文件/图像/视频上传时需要）。
|
||
|
||
说明：
|
||
- 所有 URL 均不可写死，代码已按优先级读取请求头与 APP_PUBLIC_URL/NEXTAUTH_URL 组合回退。
|
||
- 严禁将密钥写入代码或镜像层；通过环境变量注入或外部密钥管理。
|
||
|
||
### 5. 权限与角色
|
||
- 角色：USER、ADMIN、SUPER_ADMIN（最高权限）。
|
||
- 首个注册用户自动成为 SUPER_ADMIN，可在“管理后台”→“转移最高权限”移交。
|
||
- 系统设置中“用户激活功能”开关仅 SUPER_ADMIN 可修改（后端强制校验）。
|
||
- 邀请管理 UI/API 仅 ADMIN 或 SUPER_ADMIN 可见与可用。
|
||
|
||
### 6. 性能与资源控制
|
||
|
||
**核心原则**：性能开销优先，稳定性优先
|
||
|
||
- **默认限制**：
|
||
- 大文件上传采用原生 XHR，支持断点续传状态保留（localStorage），避免复杂分片服务端状态。
|
||
- 组件按需渲染，管理页数据分页/筛选（如列表增长后应启用分页）。
|
||
- 日志级别在生产降噪（仅错误/关键信息）。
|
||
|
||
- **资源管理**：
|
||
- 内存使用：空闲时 < 200MB，正常运行时 < 500MB，峰值 < 1GB
|
||
- CPU使用：空闲时 < 5%，正常运行时 < 30%，峰值 < 80%
|
||
- 数据库连接池：限制为10个连接（可在DATABASE_URL中配置）
|
||
- 文件描述符：限制并发上传为5个
|
||
|
||
- **性能优化**：
|
||
- ✅ 禁用Next.js Image Optimizer（图片已在上传时优化）
|
||
- ✅ 使用流式处理大文件，避免全部加载到内存
|
||
- ✅ 数据库查询只选择必要字段
|
||
- ✅ 实现查询结果缓存（1分钟TTL）
|
||
- ✅ 所有列表API实现分页（默认20条，最大100条）
|
||
|
||
**详细规范请参考**：[架构设计与编码规范](../架构设计与编码规范.md)
|
||
- 可配置建议：
|
||
- 通过反向代理/对象存储为大文件配置更大超时与缓冲。
|
||
- 容器资源限制：CPU/内存上限，避免同机服务互相影响。
|
||
- 关闭不需要的功能开关（如手动注册、激活制度）。
|
||
|
||
### 7. 安全与“代码加密”思路
|
||
- Web 侧使用 Next.js 产物与 Node 运行时代码，难以“加密源代码”。可行替代：
|
||
- 仅发布构建产物（生产 build）并通过容器运行，避免在目标机暴露源码与开发文件。
|
||
- 将镜像推送到私有镜像仓库（公司私有 Registry），目标机仅拉取镜像并以只读运行。
|
||
- 在容器层不包含 docs/tests/脚本等无关文件，减少代码泄露面。
|
||
- Node 层可通过混淆器做有限混淆，但会影响调试与性能，不作为默认方案。
|
||
- 后端密钥仅通过环境变量注入；数据库连接请限制来源 IP、强密码、TLS（如可用）。
|
||
|
||
### 8. 构建产物与最小化发布
|
||
- 使用 `.dockerignore` 严格排除：
|
||
- node_modules（按构建多阶段正确处理）、.git、docs、screenshots、scripts/deploy、本地开发配置、编辑器配置等。
|
||
- 采用多阶段 Dockerfile：
|
||
1) builder：安装依赖、构建 Next.js。
|
||
2) runner：仅拷贝 .next/standalone 与 .next/static（或等价产物）+ 必需文件，NODE_ENV=production。
|
||
- Compose 中将仅运行 Web/DB/MinIO（如需），不把开发脚本放进容器。
|
||
|
||
### 9. 数据库与迁移
|
||
- Prisma schema 已包含 `User.isSuperAdmin` 与 `SystemSettings.enableUserActivation`。
|
||
- 首次部署：`prisma migrate deploy` 或手动执行 SQL 保证表结构一致。
|
||
- 升级变更：随版本附带 migration 或在运维指南中标注必需 SQL（避免运行期报错）。
|
||
|
||
### 10. 上传与断点续传
|
||
- 前端以 localStorage 保存“表单与进度”快照，24 小时内提示恢复；文件句柄基于浏览器安全策略不可直接恢复，需用户重新选择文件。
|
||
- 上传接口为相对路径 `/api/materials/upload`，建议在网关/代理侧加大超时；可选配置内网域名以提升上传速度。
|
||
|
||
### 11. 链接生成与多公司部署
|
||
- 邀请链接生成顺序：`APP_PUBLIC_URL` > 请求头 `x-forwarded-host/origin/host` > 非 localhost 的 `NEXTAUTH_URL` > 兜底 `http://localhost:3000`。
|
||
- 不同公司仅需配置环境变量与系统设置，无需修改代码。
|
||
|
||
### 12. 日志与监控
|
||
- 生产日志默认记录错误与关键信息；可通过环境变量控制详细度。
|
||
- 建议接入：
|
||
- 反代访问日志（nginx/traefik）。
|
||
- Node 进程健康探针（/healthz 简易实现或容器健康检查）。
|
||
- 数据库连接/慢查询监控（PG_STAT_STATEMENTS）。
|
||
|
||
### 13. Windows/NAS 兼容注意
|
||
- Windows 部署建议使用 WSL2 或 Docker Desktop；PowerShell 脚本已提供无交互参数（注意逐条执行，不使用 &&）。
|
||
- NAS 部署（群晖/威联通）：
|
||
- 使用其 Docker/Container Manager，创建基于 compose 的栈；
|
||
- ARM 架构需选择兼容 Node 基础镜像；
|
||
- 映射持久卷：数据库数据目录、对象存储数据、上传临时目录。
|
||
|
||
### 14. 部署流程摘要（示意）
|
||
- 准备环境变量（.env 或 CI 注入）：DATABASE_URL、APP_PUBLIC_URL、NEXTAUTH_URL、NEXTAUTH_SECRET、S3_* 等。
|
||
- 构建发布镜像（本地或 CI）：
|
||
- 多阶段 Dockerfile，推送到私有仓库。
|
||
- 目标机拉取镜像并启动 compose：
|
||
- 数据库容器（或外部 DB）→ Web 容器 → 反代路由。
|
||
- 首次启动后执行 migrate（如需要）。
|
||
- 验证功能：登录、邀请、上传、系统设置（特别是用户激活开关权限）。
|
||
|
||
### 15. 变更记录（与现有实现对齐）
|
||
- 超级管理员：首个注册为 SUPER_ADMIN，可任意转移。
|
||
- 系统设置“用户激活功能”：仅 SUPER_ADMIN 可改，后端强校验。
|
||
- 邀请管理：仅 ADMIN 或 SUPER_ADMIN；链接不再写死 localhost。
|
||
- 用户管理：以“最高权限”为根；部门管理员置顶并合并展示。
|
||
- 断点续传：前端持久化上传状态，重开页面可恢复。
|
||
|
||
### 16. 代码约束清单（评审基准）
|
||
- 所有可变项必须通过环境变量/系统设置注入；不得硬编码公司/域名。
|
||
- 不向生产镜像引入与运行无关目录/文件（docs、脚本、图像等）。
|
||
- 低开销优先：避免不必要的实时统计、全量加载、大对象驻留。
|
||
- API 权限严谨：前端可见性与后端接口权限双保险。
|
||
- 迁移/变更必须提供 DB 同步方案（migrate 或 SQL 说明）。
|
||
|
||
如需新增公司特定行为，必须通过配置开关或注入策略实现；不允许分叉硬编码。以后开发以此文档为主，必要时补充版本控制的“变更记录”。
|
||
|
||
|