11 KiB
11 KiB
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 私有仓库
# 注册 Docker Hub 账号: https://hub.docker.com/
# 创建私有仓库
# 设置环境变量
export DOCKER_REGISTRY=yourusername
方案B: 阿里云容器镜像服务
# 登录: https://cr.console.aliyun.com/
# 创建命名空间和仓库
# 设置环境变量
export DOCKER_REGISTRY=registry.cn-hangzhou.aliyuncs.com/your_namespace
方案C: 自建 Harbor
# 部署 Harbor: https://goharbor.io/
# 创建项目
# 设置环境变量
export DOCKER_REGISTRY=your-harbor.com/project
2. 修改构建脚本
编辑 build-and-push.sh:
# 修改默认仓库地址
DOCKER_REGISTRY="${DOCKER_REGISTRY:-your-registry.com}"
🚀 打包步骤
第一步: 构建并推送镜像
# 给脚本添加执行权限（Linux/Mac）
chmod +x build-and-push.sh
# Windows 用户在 Git Bash 中执行
# 或使用 WSL
# 执行构建
./build-and-push.sh
脚本会提示：
- 输入版本号（如: 1.0.0）
- 确认构建信息
- 自动构建、测试、推送镜像
- 询问是否生成发布包
第二步: 验证镜像
# 检查镜像是否存在
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: 镜像仓库权限控制
# 为客户创建只读账号
# Docker Hub: 添加 Collaborator
# Harbor: 创建 Robot Account
# 阿里云: 创建子账号
# 客户使用时需要登录
docker login your-registry.com
# 输入提供的账号密码
方式2: License Key 验证
在应用代码中添加 License 验证：
// 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')
}
🎁 交付给客户
交付清单
- 发布包:
release-v1.0.0.tar.gz - 镜像访问凭证（如需要）:
- 仓库地址
- 用户名
- 密码
- License Key（如实施）
- 安装文档: 发布包内的
README.md - 技术支持方式
交付方式
方式A: 在线下载
# 客户执行
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盘或光盘，适用于无法联网的环境
客户安装步骤
# 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
🔄 版本更新流程
发布新版本
# 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 提供给客户
客户升级步骤
# 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 验证正常（如有）
- 准备好技术支持
🧪 测试和验证
本地测试
# 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
性能测试
# 并发测试
ab -n 1000 -c 10 http://localhost:4320/
# 大文件上传测试
# 通过界面上传 100MB+ 文件
# 资源监控
docker stats
📝 常见问题
Q: 如何处理敏感信息？
A:
- 不要在镜像中硬编码密码
- 使用环境变量
- 提供 .env.template 而非实际配置
- 文档中说明需要修改的配置
Q: 如何防止客户转售？
A:
- 实施 License Key 验证
- 绑定硬件信息（MAC地址）
- 在用户协议中明确禁止
- 联网验证（可选）
Q: 如何支持离线安装？
A:
- 将镜像导出:
docker save -o image.tar - 在发布包中包含镜像文件
- 修改 install.sh 从本地加载镜像
- 缺点：包体积大
Q: 如何提供试用版？
A:
- 生成 30 天试用 License
- 限制功能（如用户数）
- 在应用中检查 License 过期时间
Q: 客户无法访问镜像仓库怎么办？
A:
- 检查仓库是否公开（或提供了凭证）
- 检查网络连接
- 提供国内镜像源
- 提供离线安装包
🎯 最佳实践
-
版本管理
- 使用语义化版本号（Semantic Versioning）
- 保持向后兼容
- 提供升级文档
-
文档完善
- 详细的安装文档
- 清晰的故障排查指南
- 常见问题 FAQ
-
自动化测试
- 每次发布前运行测试脚本
- 验证所有功能
- 记录测试结果
-
客户支持
- 提供技术支持渠道
- 收集客户反馈
- 持续改进产品
-
安全性
- 定期更新依赖
- 修复安全漏洞
- 及时发布补丁
📞 需要帮助？
如在打包过程中遇到问题：
- 检查
build-and-push.sh的输出 - 验证镜像仓库配置
- 查看 Docker 构建日志
- 在测试环境验证
祝打包顺利！🚀