sillytavern-repalice/DISTRIBUTION-STRATEGY.md

📦 项目分发指南

🎯 推荐方案：保持双容器架构（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. 用户操作流程：

   # 克隆仓库
   git clone <repository-url>
   cd sillytavern-repalice
   
   # 配置环境变量
   cp .env.example .env
   # 编辑 .env 文件
   
   # 启动应用
   docker-compose up -d
   

优点：

• ✅ 最简单，无需额外配置
• ✅ 用户可以自定义修改
• ✅ 透明度高

缺点：

• ❌ 首次构建较慢
• ❌ 需要安装 Git

---

方式 2：推送到 Docker Hub（推荐）

适用场景：公开发布、简化用户操作

步骤：

1. 构建并推送镜像：

   # 登录 Docker Hub
   docker login
   
   # 运行发布脚本
   .\publish-docker.bat
   # 输入版本号，例如：1.0.0
   

2. 创建简化的 docker-compose.yml（给用户）：

   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. 用户操作流程：

   # 下载 docker-compose.yml 和 .env.example
   # 配置 .env 文件
   
   # 直接启动（自动拉取镜像）
   docker-compose up -d
   

优点：

• ✅ 启动速度快（无需构建）
• ✅ 用户操作简单
• ✅ 版本管理清晰

缺点：

• ❌ 需要 Docker Hub 账号
• ❌ 镜像占用存储空间

---

方式 3：导出镜像文件（离线分发）

适用场景：内网环境、无法访问 Docker Hub

步骤：

1. 构建并导出镜像：

   # 构建镜像
   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. 用户操作流程：

   # 解压
   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：

# 快速开始

## 1. 前置要求

- 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)

## 2. 配置

```bash
# 复制环境变量文件
cp .env.example .env

# 编辑 .env，填入您的 API 密钥
notepad .env

3. 启动

docker-compose up -d

4. 访问

• 前端：http://localhost:5173
• 后端：http://localhost:3000

5. 停止

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. 开发者：

   # 构建并发布
   .\publish-docker.bat
   

2. 用户：

   # 下载配置文件
   # 配置 .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>

---

祝您分发顺利！ 🎉