# FLNXI素材库 - 开发者打包指南 ## 📦 打包流程总览 本文档说明如何将项目打包成可销售的私有镜像产品。 ## 🎯 打包方案架构 ### 完整架构图 ``` ┌─────────────────────────────────────────────┐ │ 开发环境 │ │ ┌────────────────────────────────┐ │ │ │ 源代码 + Dockerfile │ │ │ └────────────┬───────────────────┘ │ │ │ build & push │ │ ↓ │ │ ┌────────────────────────────────┐ │ │ │ 私有Docker镜像仓库 │ │ │ │ (Harbor/阿里云/Docker Hub) │ │ │ └────────────┬───────────────────┘ │ └───────────────┼──────────────────────────────┘ │ │ 提供给客户 ↓ ┌─────────────────────────────────────────────┐ │ 客户环境 │ │ ┌────────────────────────────────┐ │ │ │ 发布包 (release-vX.X.X) │ │ │ │ - docker-compose.yml │ │ │ │ - .env │ │ │ │ - install.sh │ │ │ └────────────┬───────────────────┘ │ │ │ ./install.sh │ │ ↓ │ │ ┌────────────────────────────────┐ │ │ │ 完整系统运行 │ │ │ │ - 应用 (私有镜像) │ │ │ │ - PostgreSQL │ │ │ │ - MinIO │ │ │ └────────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` ## 📋 准备工作 ### 1. 配置私有镜像仓库 选择以下任一方案： #### 方案A: Docker Hub 私有仓库 ```bash # 注册 Docker Hub 账号: https://hub.docker.com/ # 创建私有仓库 # 设置环境变量 export DOCKER_REGISTRY=yourusername ``` #### 方案B: 阿里云容器镜像服务 ```bash # 登录: https://cr.console.aliyun.com/ # 创建命名空间和仓库 # 设置环境变量 export DOCKER_REGISTRY=registry.cn-hangzhou.aliyuncs.com/your_namespace ``` #### 方案C: 自建 Harbor ```bash # 部署 Harbor: https://goharbor.io/ # 创建项目 # 设置环境变量 export DOCKER_REGISTRY=your-harbor.com/project ``` ### 2. 修改构建脚本 编辑 `build-and-push.sh`: ```bash # 修改默认仓库地址 DOCKER_REGISTRY="${DOCKER_REGISTRY:-your-registry.com}" ``` ## 🚀 打包步骤 ### 第一步: 构建并推送镜像 ```bash # 给脚本添加执行权限（Linux/Mac） chmod +x build-and-push.sh # Windows 用户在 Git Bash 中执行 # 或使用 WSL # 执行构建 ./build-and-push.sh ``` 脚本会提示： 1. 输入版本号（如: 1.0.0） 2. 确认构建信息 3. 自动构建、测试、推送镜像 4. 询问是否生成发布包 ### 第二步: 验证镜像 ```bash # 检查镜像是否存在 docker images | grep flnxi-material # 测试镜像 docker run --rm your-registry.com/flnxi-material:1.0.0 node --version ``` ### 第三步: 生成发布包 构建脚本会自动生成 `release-vX.X.X.tar.gz`，包含： ``` release-v1.0.0/ ├── docker-compose.yml # 生产环境配置 ├── .env # 环境变量模板 ├── install.sh # 一键安装脚本 ├── quick-start.sh # 快速启动 ├── healthcheck.sh # 健康检查 ├── uninstall.sh # 卸载脚本 ├── README.md # 客户使用文档 ├── IMAGE_INFO.txt # 镜像信息 └── VERSION.txt # 版本信息 ``` ## 📁 发布包文件说明 ### docker-compose.yml 使用 `docker-compose.prod.yml` 作为模板，特点： - 使用 `image:` 拉取私有镜像，而非 `build:` - 包含 PostgreSQL 和 MinIO - 支持环境变量配置 - 包含健康检查 ### .env 环境配置文件，客户需要修改： - `SERVER_IP`: 服务器IP地址（必须） - `APP_PORT`: 应用端口（可选） - `POSTGRES_PASSWORD`: 数据库密码（建议修改） - `MINIO_ROOT_PASSWORD`: MinIO密码（建议修改） ### install.sh 一键安装脚本，功能： - ✅ 检查 Docker 环境 - ✅ 自动检测服务器 IP - ✅ 生成随机密码 - ✅ 创建配置文件 - ✅ 拉取镜像 - ✅ 启动服务 - ✅ 初始化数据库 - ✅ 配置 MinIO bucket ## 🔐 镜像访问控制 ### 方式1: 镜像仓库权限控制 ```bash # 为客户创建只读账号 # Docker Hub: 添加 Collaborator # Harbor: 创建 Robot Account # 阿里云: 创建子账号 # 客户使用时需要登录 docker login your-registry.com # 输入提供的账号密码 ``` ### 方式2: License Key 验证 在应用代码中添加 License 验证： ```typescript // lib/license.ts export async function verifyLicense() { const licenseKey = process.env.LICENSE_KEY if (!licenseKey) { throw new Error('License key is required') } // 验证逻辑 // 1. 检查格式 // 2. 验证签名 // 3. 检查过期时间 // 4. 可选：联网验证 return true } // middleware.ts 或 app/layout.tsx import { verifyLicense } from '@/lib/license' if (!await verifyLicense()) { throw new Error('Invalid license') } ``` ## 🎁 交付给客户 ### 交付清单 1. **发布包**: `release-v1.0.0.tar.gz` 2. **镜像访问凭证**（如需要）: - 仓库地址 - 用户名 - 密码 3. **License Key**（如实施） 4. **安装文档**: 发布包内的 `README.md` 5. **技术支持方式** ### 交付方式 #### 方式A: 在线下载 ```bash # 客户执行 wget https://your-domain.com/releases/flnxi-material-v1.0.0.tar.gz # 或 curl -O https://your-domain.com/releases/flnxi-material-v1.0.0.tar.gz ``` #### 方式B: 私有下载链接 使用云存储服务生成临时下载链接（24小时有效） #### 方式C: 物理介质 刻录到U盘或光盘，适用于无法联网的环境 ### 客户安装步骤 ```bash # 1. 解压 tar -xzf flnxi-material-v1.0.0.tar.gz cd flnxi-material-v1.0.0 # 2. 配置 vim .env # 修改 SERVER_IP # 3. 安装 chmod +x *.sh ./install.sh # 4. 访问 # http://SERVER_IP:4320 ``` ## 🔄 版本更新流程 ### 发布新版本 ```bash # 1. 更新代码 git pull git checkout main # 2. 修改版本号 vim package.json # 更新 version vim VERSION.txt # 添加更新日志 # 3. 构建新版本 ./build-and-push.sh # 输入新版本号，如: 1.1.0 # 4. 测试新版本 # 在测试环境验证 # 5. 发布 # 将 release-v1.1.0.tar.gz 提供给客户 ``` ### 客户升级步骤 ```bash # 1. 备份数据 docker compose exec postgres pg_dump -U postgres flnxi > backup.sql tar -czf uploads_backup.tar.gz uploads/ # 2. 下载新版本配置 # 获取新的 docker-compose.yml（如有变化） # 3. 停止服务 docker compose down # 4. 更新镜像 # 方法1: 修改 .env 中的 IMAGE_TAG vim .env # IMAGE_TAG=1.1.0 docker compose pull # 方法2: 直接拉取 docker pull your-registry.com/flnxi-material:1.1.0 # 5. 启动服务 docker compose up -d # 6. 验证 ./test-deployment.sh ``` ## 📊 打包检查清单 在发布前，确认以下事项： - [ ] 代码已提交到主分支 - [ ] 版本号已更新（package.json, VERSION.txt） - [ ] 镜像构建成功 - [ ] 镜像已推送到仓库 - [ ] 发布包已生成 - [ ] 在测试环境验证安装 - [ ] 所有脚本有执行权限 - [ ] 文档已更新 - [ ] LICENSE 验证正常（如有） - [ ] 准备好技术支持 ## 🧪 测试和验证 ### 本地测试 ```bash # 1. 解压发布包 tar -xzf release-v1.0.0.tar.gz cd release-v1.0.0 # 2. 配置环境 cp .env .env.test vim .env.test # 设置测试配置 # 3. 安装 ./install.sh # 4. 运行测试 ./test-deployment.sh # 5. 功能测试 # - 注册账号 # - 上传素材 # - 下载素材 # - 管理功能 # 6. 清理 ./uninstall.sh ``` ### 性能测试 ```bash # 并发测试 ab -n 1000 -c 10 http://localhost:4320/ # 大文件上传测试 # 通过界面上传 100MB+ 文件 # 资源监控 docker stats ``` ## 📝 常见问题 ### Q: 如何处理敏感信息？ A: 1. 不要在镜像中硬编码密码 2. 使用环境变量 3. 提供 .env.template 而非实际配置 4. 文档中说明需要修改的配置 ### Q: 如何防止客户转售？ A: 1. 实施 License Key 验证 2. 绑定硬件信息（MAC地址） 3. 在用户协议中明确禁止 4. 联网验证（可选） ### Q: 如何支持离线安装？ A: 1. 将镜像导出: `docker save -o image.tar` 2. 在发布包中包含镜像文件 3. 修改 install.sh 从本地加载镜像 4. 缺点：包体积大 ### Q: 如何提供试用版？ A: 1. 生成 30 天试用 License 2. 限制功能（如用户数） 3. 在应用中检查 License 过期时间 ### Q: 客户无法访问镜像仓库怎么办？ A: 1. 检查仓库是否公开（或提供了凭证） 2. 检查网络连接 3. 提供国内镜像源 4. 提供离线安装包 ## 🎯 最佳实践 1. **版本管理** - 使用语义化版本号（Semantic Versioning） - 保持向后兼容 - 提供升级文档 2. **文档完善** - 详细的安装文档 - 清晰的故障排查指南 - 常见问题 FAQ 3. **自动化测试** - 每次发布前运行测试脚本 - 验证所有功能 - 记录测试结果 4. **客户支持** - 提供技术支持渠道 - 收集客户反馈 - 持续改进产品 5. **安全性** - 定期更新依赖 - 修复安全漏洞 - 及时发布补丁 ## 📞 需要帮助？ 如在打包过程中遇到问题： 1. 检查 `build-and-push.sh` 的输出 2. 验证镜像仓库配置 3. 查看 Docker 构建日志 4. 在测试环境验证 --- **祝打包顺利！🚀**