flnxi-Wu/docs/guides/DEPLOYMENT_GUIDE.md
WuYongJie d1c6efc79d
Some checks failed
CI Check / check (push) Has been cancelled
feat: NAS 部署与 Harbor 推送流程
2025-12-03 14:39:06 +08:00

405 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# FLNXI素材库 - 部署指南(开发者)
## 项目打包出售方案
本项目已配置为可打包成私有 Docker 镜像进行销售的完整方案,包含以下组件:
- ✅ **主应用**: Next.js 应用(私有镜像)
- ✅ **PostgreSQL**: 数据库(公开镜像)
- ✅ **MinIO**: 对象存储(公开镜像)
- ✅ **自动配置**: 一键安装脚本
## 架构说明
### 完整架构
```
┌─────────────────────────────────────────────┐
│ 客户服务器 (一键部署) │
├─────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 应用服务 │ │ PostgreSQL │ │
│ │ (私有镜像) │←→│ 数据库 │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ↓ │
│ ┌──────────────┐ │
│ │ MinIO │ │
│ │ 对象存储 │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────┘
```
### 核心优势
1. **完全独立**: 客户无需外部依赖,所有服务都在本地运行
2. **一键部署**: 自动配置数据库、MinIO、网络等
3. **数据私有**: 所有数据保存在客户服务器,安全可控
4. **易于维护**: 标准 Docker 部署,方便升级和维护
## 构建和发布流程
### 1. 准备私有镜像仓库
选择以下任一方式:
#### 方案A: 使用 Docker Hub (私有仓库)
```bash
# 登录 Docker Hub
docker login
# 设置环境变量
export DOCKER_REGISTRY=yourusername
```
#### 方案B: 使用阿里云容器镜像服务
```bash
# 登录阿里云
docker login --username=your_username registry.cn-hangzhou.aliyuncs.com
# 设置环境变量
export DOCKER_REGISTRY=registry.cn-hangzhou.aliyuncs.com/your_namespace
```
#### 方案C: 自建 Harbor 私有仓库
```bash
# 登录 Harbor
docker login your-harbor.com
# 设置环境变量
export DOCKER_REGISTRY=your-harbor.com/project
```
### 2. 修改构建配置
编辑 `build-and-push.sh`,修改默认仓库地址:
```bash
DOCKER_REGISTRY="${DOCKER_REGISTRY:-your-registry.com}"
```
### 3. 构建并推送镜像
```bash
# 添加执行权限
chmod +x build-and-push.sh
# 执行构建
./build-and-push.sh
```
脚本会:
1. 提示输入版本号(如 1.0.0)
2. 构建 Docker 镜像
3. 测试镜像是否正常
4. 推送到私有仓库
5. 生成客户发布包
### 4. 发布包内容
生成的发布包 `release-vX.X.X.tar.gz` 包含:
```
release-v1.0.0/
├── docker-compose.yml # Docker 编排文件
├── .env # 环境配置模板
├── install.sh # 一键安装脚本
├── quick-start.sh # 快速启动脚本
├── README.md # 客户使用文档
└── IMAGE_INFO.txt # 镜像信息
```
## 客户使用流程
### 1. 提供给客户
将以下内容提供给客户:
1. 发布包:`release-vX.X.X.tar.gz`
2. 镜像访问权限(如果使用私有仓库)
3. 使用文档:发布包内的 `README.md`
### 2. 客户安装步骤
```bash
# 1. 解压
tar -xzf release-v1.0.0.tar.gz
cd release-v1.0.0
# 2. 配置环境(修改 .env 文件)
vim .env
# 3. 安装
chmod +x *.sh
./install.sh
```
### 3. 安装过程自动完成
- ✅ 检测 Docker 环境
- ✅ 自动检测服务器 IP
- ✅ 生成随机安全密码
- ✅ 拉取镜像(PostgreSQL, MinIO, 应用)
- ✅ 启动所有服务
- ✅ 初始化数据库
- ✅ 配置 MinIO bucket
- ✅ 显示访问信息
## 镜像更新流程
### 发布新版本
```bash
# 1. 更新代码
git pull
# 2. 修改版本号(建议在 package.json 中同步)
vim package.json
# 3. 构建新版本
./build-and-push.sh
# 输入新版本号,如: 1.1.0
# 4. 将新的发布包提供给客户
# 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 down
# 3. 拉取新镜像(编辑 .env 修改 IMAGE_TAG)
vim .env # 修改 IMAGE_TAG=1.1.0
docker compose pull
# 4. 启动服务
docker compose up -d
```
## MinIO 配置说明
### 自动初始化
`minio-init` 服务会自动:
1. 连接到 MinIO
2. 创建指定的 bucket(默认: youyidian3d)
3. 设置 bucket 为公开读取
4. 完成后自动退出
### 访问配置
应用内部访问 MinIO:
```
S3_ENDPOINT=http://minio:9000
```
外部访问(用户浏览器):
```
S3_PUBLIC_DOMAIN=http://${SERVER_IP}:9000/${S3_BUCKET}
```
### MinIO 控制台
客户可以通过 MinIO 控制台管理文件:
```
地址: http://SERVER_IP:9001
用户名: minioadmin
密码: (在 .env 中配置)
```
## 定价和授权策略建议
### 方案A: 按实例授权
- 一次性购买
- 绑定服务器 IP 或 MAC 地址
- 通过 License Key 激活
### 方案B: 订阅制
- 按年/月收费
- 定期验证 License
- 过期后停止服务
### 方案C: 版本授权
- 买断当前版本
- 升级新版本需额外付费
- 提供有限期的更新支持
### 实施 License 验证
可以在应用中添加 License 验证逻辑:
```typescript
// lib/license.ts
export async function verifyLicense(licenseKey: string) {
// 1. 验证 License Key 格式
// 2. 联网验证(可选)
// 3. 检查过期时间
// 4. 验证服务器信息
return { valid: true, expiresAt: '2025-12-31' }
}
```
## 安全措施
### 1. 代码保护
- ✅ 使用 Docker 镜像(代码不可见)
- ✅ Next.js 生产构建(代码混淆)
- ⚠️ 建议:添加代码加密
### 2. 镜像保护
```bash
# 使用私有仓库
DOCKER_REGISTRY=your-private-registry.com
# 启用镜像签名(Docker Content Trust)
export DOCKER_CONTENT_TRUST=1
```
### 3. License 保护
在应用启动时验证 License:
```typescript
// middleware.ts 或 app/layout.tsx
import { verifyLicense } from '@/lib/license'
// 启动时验证
if (!await verifyLicense(process.env.LICENSE_KEY)) {
throw new Error('Invalid license')
}
```
### 4. 数据库加密
```yaml
# docker-compose.yml
postgres:
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
# 启用数据加密
command: postgres -c ssl=on -c ssl_cert_file=/certs/cert.pem
```
## 技术支持方案
### 日志收集
```bash
# 收集所有日志
docker compose logs > logs.txt
# 收集系统信息
docker compose ps >> logs.txt
docker version >> logs.txt
```
### 远程支持
```bash
# 方案1: 通过 SSH 远程协助
ssh user@customer-server
# 方案2: 使用 Portainer(可选)
docker run -d -p 9000:9000 \
-v /var/run/docker.sock:/var/run/docker.sock \
portainer/portainer-ce
```
## 常见问题
### Q: 如何限制客户的部署数量?
A: 可以通过以下方式:
1. License Key 绑定 MAC 地址
2. 在应用中实施激活验证
3. 通过 API 统计和限制激活次数
### Q: 如何防止客户转售?
A:
1. License 绑定硬件信息
2. 定期联网验证
3. 在用户协议中明确禁止
### Q: 客户如何迁移到新服务器?
A: 提供迁移服务:
1. 备份数据
2. 导出数据库和文件
3. 在新服务器安装
4. 恢复数据
5. 重新激活 License(如果绑定硬件)
### Q: 如何提供试用版?
A:
1. 提供 30 天试用 License
2. 限制功能(如用户数、存储空间)
3. 试用期后要求输入正式 License
## 成本估算
### 开发成本
- 私有镜像仓库: $0-50/月(取决于方案)
- SSL 证书: $0(Let's Encrypt)或 $10-100/年
- 域名: $10-20/年(如果需要)
### 客户成本
- 服务器: 2GB 内存,10GB 磁盘,约 $5-20/月
- 备份存储: 额外空间需求
- 带宽: 根据用户量
## 总结
这套方案提供了:
✅ **完整的私有部署方案**
- 包含数据库、对象存储、应用
- 一键安装,自动配置
- 所有数据客户私有
✅ **商业化友好**
- Docker 镜像保护代码
- 易于添加 License 验证
- 支持版本管理和升级
✅ **易于销售和交付**
- 标准化部署流程
- 完整的客户文档
- 简化技术支持
✅ **可持续发展**
- 容易发布更新
- 支持多种授权模式
- 便于扩展功能
开始构建您的第一个发布版本:
```bash
./build-and-push.sh
```
祝生意兴隆!🚀