8.4 KiB
8.4 KiB
可移植部署与生产规范（权威版）
本指南用于指导将本项目部署到任意公司、任意服务器（含 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条）
详细规范请参考：架构设计与编码规范
- 可配置建议：
- 通过反向代理/对象存储为大文件配置更大超时与缓冲。
- 容器资源限制：CPU/内存上限，避免同机服务互相影响。
- 关闭不需要的功能开关（如手动注册、激活制度）。
7. 安全与“代码加密”思路
- Web 侧使用 Next.js 产物与 Node 运行时代码，难以“加密源代码”。可行替代：
- 仅发布构建产物（生产 build）并通过容器运行，避免在目标机暴露源码与开发文件。
- 将镜像推送到私有镜像仓库（公司私有 Registry），目标机仅拉取镜像并以只读运行。
- 在容器层不包含 docs/tests/脚本等无关文件，减少代码泄露面。
- Node 层可通过混淆器做有限混淆，但会影响调试与性能，不作为默认方案。
- 后端密钥仅通过环境变量注入；数据库连接请限制来源 IP、强密码、TLS（如可用）。
8. 构建产物与最小化发布
- 使用
.dockerignore严格排除：- node_modules（按构建多阶段正确处理）、.git、docs、screenshots、scripts/deploy、本地开发配置、编辑器配置等。
- 采用多阶段 Dockerfile：
- builder：安装依赖、构建 Next.js。
- 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 说明）。
如需新增公司特定行为，必须通过配置开关或注入策略实现；不允许分叉硬编码。以后开发以此文档为主，必要时补充版本控制的“变更记录”。