360 lines
7.1 KiB
Markdown
360 lines
7.1 KiB
Markdown
# 📦 项目分发指南
|
||
|
||
## 🎯 推荐方案：保持双容器架构（Vite + Nginx）
|
||
|
||
### 为什么选择双容器？
|
||
|
||
1. **性能最优**：Nginx 是专业的静态文件服务器，性能远超 Node.js
|
||
2. **职责清晰**：前后端分离，便于维护和扩展
|
||
3. **行业标准**：这是业界最佳实践
|
||
4. **部署简单**：用户只需一条命令 `docker-compose up -d`
|
||
|
||
---
|
||
|
||
## 📋 分发方式
|
||
|
||
### 方式 1：提供源代码 + docker-compose.yml（最简单）
|
||
|
||
**适用场景**：开源项目、团队协作
|
||
|
||
**步骤**：
|
||
|
||
1. 确保以下文件在仓库中：
|
||
- `docker-compose.yml`
|
||
- `docker/backend.Dockerfile`
|
||
- `docker/frontend.Dockerfile`
|
||
- `.env.example`
|
||
- `DISTRIBUTION-GUIDE.md`
|
||
|
||
2. 用户操作流程：
|
||
```bash
|
||
# 克隆仓库
|
||
git clone <repository-url>
|
||
cd sillytavern-repalice
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 文件
|
||
|
||
# 启动应用
|
||
docker-compose up -d
|
||
```
|
||
|
||
**优点**：
|
||
- ✅ 最简单，无需额外配置
|
||
- ✅ 用户可以自定义修改
|
||
- ✅ 透明度高
|
||
|
||
**缺点**：
|
||
- ❌ 首次构建较慢
|
||
- ❌ 需要安装 Git
|
||
|
||
---
|
||
|
||
### 方式 2：推送到 Docker Hub（推荐）
|
||
|
||
**适用场景**：公开发布、简化用户操作
|
||
|
||
**步骤**：
|
||
|
||
1. **构建并推送镜像**：
|
||
```bash
|
||
# 登录 Docker Hub
|
||
docker login
|
||
|
||
# 运行发布脚本
|
||
.\publish-docker.bat
|
||
# 输入版本号，例如：1.0.0
|
||
```
|
||
|
||
2. **创建简化的 docker-compose.yml**（给用户）：
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
backend:
|
||
image: yourusername/sillytavern-repalice-backend:latest
|
||
container_name: sillytavern-backend
|
||
ports:
|
||
- "3000:3000"
|
||
volumes:
|
||
- ./data:/app/data
|
||
environment:
|
||
- NODE_ENV=production
|
||
- PORT=3000
|
||
- DATA_DIR=/app/data
|
||
env_file:
|
||
- .env
|
||
restart: unless-stopped
|
||
|
||
frontend:
|
||
image: yourusername/sillytavern-repalice-frontend:latest
|
||
container_name: sillytavern-frontend
|
||
ports:
|
||
- "5173:5173"
|
||
environment:
|
||
- VITE_API_URL=http://localhost:3000/api
|
||
depends_on:
|
||
- backend
|
||
restart: unless-stopped
|
||
```
|
||
|
||
3. **用户操作流程**：
|
||
```bash
|
||
# 下载 docker-compose.yml 和 .env.example
|
||
# 配置 .env 文件
|
||
|
||
# 直接启动（自动拉取镜像）
|
||
docker-compose up -d
|
||
```
|
||
|
||
**优点**：
|
||
- ✅ 启动速度快（无需构建）
|
||
- ✅ 用户操作简单
|
||
- ✅ 版本管理清晰
|
||
|
||
**缺点**：
|
||
- ❌ 需要 Docker Hub 账号
|
||
- ❌ 镜像占用存储空间
|
||
|
||
---
|
||
|
||
### 方式 3：导出镜像文件（离线分发）
|
||
|
||
**适用场景**：内网环境、无法访问 Docker Hub
|
||
|
||
**步骤**：
|
||
|
||
1. **构建并导出镜像**：
|
||
```bash
|
||
# 构建镜像
|
||
docker-compose build
|
||
|
||
# 导出为 tar 文件
|
||
docker save sillytavern-repalice-backend:latest -o backend.tar
|
||
docker save sillytavern-repalice-frontend:latest -o frontend.tar
|
||
|
||
# 压缩
|
||
tar -czf sillytavern-images.tar.gz backend.tar frontend.tar
|
||
```
|
||
|
||
2. **用户提供**：
|
||
- `sillytavern-images.tar.gz`
|
||
- `docker-compose.yml`
|
||
- `.env.example`
|
||
- 导入脚本
|
||
|
||
3. **用户操作流程**：
|
||
```bash
|
||
# 解压
|
||
tar -xzf sillytavern-images.tar.gz
|
||
|
||
# 导入镜像
|
||
docker load -i backend.tar
|
||
docker load -i frontend.tar
|
||
|
||
# 启动
|
||
docker-compose up -d
|
||
```
|
||
|
||
**优点**：
|
||
- ✅ 完全离线可用
|
||
- ✅ 适合内网环境
|
||
|
||
**缺点**：
|
||
- ❌ 文件体积大
|
||
- ❌ 分发不便
|
||
|
||
---
|
||
|
||
## 📝 分发包结构
|
||
|
||
### 最小化分发包
|
||
|
||
```
|
||
sillytavern-repalice/
|
||
├── docker-compose.yml # Docker Compose 配置
|
||
├── .env.example # 环境变量示例
|
||
├── DISTRIBUTION-GUIDE.md # 分发指南
|
||
└── README.md # 使用说明
|
||
```
|
||
|
||
### 完整分发包（含源码）
|
||
|
||
```
|
||
sillytavern-repalice/
|
||
├── docker/
|
||
│ ├── backend.Dockerfile
|
||
│ └── frontend.Dockerfile
|
||
├── server/ # 后端源码
|
||
├── client/ # 前端源码
|
||
├── shared/ # 共享模块
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
├── .dockerignore
|
||
├── package.json
|
||
├── DISTRIBUTION-GUIDE.md
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 用户快速开始模板
|
||
|
||
创建一个 `QUICKSTART.md`：
|
||
|
||
```markdown
|
||
# 快速开始
|
||
|
||
## 1. 前置要求
|
||
|
||
- 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)
|
||
|
||
## 2. 配置
|
||
|
||
```bash
|
||
# 复制环境变量文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env，填入您的 API 密钥
|
||
notepad .env
|
||
```
|
||
|
||
## 3. 启动
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 4. 访问
|
||
|
||
- 前端：http://localhost:5173
|
||
- 后端：http://localhost:3000
|
||
|
||
## 5. 停止
|
||
|
||
```bash
|
||
docker-compose down
|
||
```
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 最佳实践建议
|
||
|
||
### 1. 版本管理
|
||
|
||
使用语义化版本号：
|
||
- `v1.0.0` - 主版本
|
||
- `v1.1.0` - 次版本
|
||
- `v1.0.1` - 补丁版本
|
||
|
||
### 2. 文档完善
|
||
|
||
提供以下文档：
|
||
- `README.md` - 项目介绍
|
||
- `DISTRIBUTION-GUIDE.md` - 分发指南
|
||
- `QUICKSTART.md` - 快速开始
|
||
- `.env.example` - 环境变量说明
|
||
|
||
### 3. 自动化脚本
|
||
|
||
提供便捷脚本：
|
||
- `build-docker.ps1` - 构建脚本
|
||
- `publish-docker.bat` - 发布脚本
|
||
- `start-dev.ps1` - 开发启动脚本
|
||
|
||
### 4. CI/CD（可选）
|
||
|
||
配置 GitHub Actions 自动构建和推送：
|
||
|
||
```yaml
|
||
name: Build and Push Docker Images
|
||
|
||
on:
|
||
push:
|
||
tags:
|
||
- 'v*'
|
||
|
||
jobs:
|
||
build-and-push:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- name: Login to Docker Hub
|
||
uses: docker/login-action@v2
|
||
with:
|
||
username: ${{ secrets.DOCKER_USERNAME }}
|
||
password: ${{ secrets.DOCKER_PASSWORD }}
|
||
|
||
- name: Build and push
|
||
run: |
|
||
docker-compose build
|
||
docker-compose push
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 方案对比总结
|
||
|
||
| 方案 | 复杂度 | 启动速度 | 适用场景 |
|
||
|------|--------|----------|----------|
|
||
| 源码 + docker-compose | ⭐ | 🐌 慢 | 开源项目、开发团队 |
|
||
| Docker Hub 镜像 | ⭐⭐ | ⚡ 快 | 公开发布、生产环境 |
|
||
| 离线镜像文件 | ⭐⭐⭐ | ⚡ 快 | 内网环境、安全要求高 |
|
||
|
||
---
|
||
|
||
## 🎯 我的推荐
|
||
|
||
**对于大多数场景，推荐使用方式 2（Docker Hub 镜像）**：
|
||
|
||
1. **开发者**：
|
||
```bash
|
||
# 构建并发布
|
||
.\publish-docker.bat
|
||
```
|
||
|
||
2. **用户**：
|
||
```bash
|
||
# 下载配置文件
|
||
# 配置 .env
|
||
docker-compose up -d
|
||
```
|
||
|
||
**优势**：
|
||
- ✅ 用户体验最好（启动快）
|
||
- ✅ 维护成本低
|
||
- ✅ 版本管理清晰
|
||
- ✅ 符合行业标准
|
||
|
||
---
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 为什么不合并成一个容器？
|
||
|
||
**A**:
|
||
- Nginx 性能远优于 Node.js 提供静态文件
|
||
- 前后端分离便于独立升级和维护
|
||
- 两个容器的 overhead 很小
|
||
|
||
### Q: 用户觉得两个容器太复杂怎么办？
|
||
|
||
**A**:
|
||
- Docker Compose 已经简化了操作（一条命令）
|
||
- 提供详细的文档和脚本
|
||
- 可以制作一键启动脚本
|
||
|
||
### Q: 如何确保镜像安全性？
|
||
|
||
**A**:
|
||
- 使用官方基础镜像（node:20-alpine, nginx:alpine）
|
||
- 定期更新依赖
|
||
- 扫描漏洞：`docker scan <image>`
|
||
|
||
---
|
||
|
||
**祝您分发顺利！** 🎉
|