455 lines
11 KiB
Markdown
455 lines
11 KiB
Markdown
# 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. 在测试环境验证
|
||
|
||
---
|
||
|
||
**祝打包顺利！🚀**
|
||
|
||
|
||
|