前端修饰与渲染处理

2026-04-26 03:34:47 +08:00
parent 35eff3faf6
commit 6b5ddac178
114 changed files with 18465 additions and 132 deletions
--- a/DISTRIBUTION-STRATEGY.md
+++ b/DISTRIBUTION-STRATEGY.md
@@ -0,0 +1,359 @@
+# 📦 项目分发指南
+
+## 🎯 推荐方案：保持双容器架构（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>`
+
+---
+
+**祝您分发顺利！** 🎉