# 📦 项目分发指南

## 🎯 推荐方案：保持双容器架构（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>`

---

**祝您分发顺利！** 🎉