316 lines
6.6 KiB
Markdown
316 lines
6.6 KiB
Markdown
# 📦 项目分发清单
|
||
|
||
## ✅ 已完成配置
|
||
|
||
### 1. Docker 配置
|
||
- ✅ `docker-compose.yml` - 开发/生产通用配置
|
||
- ✅ `docker-compose.prod.yml` - 生产环境配置（使用预构建镜像）
|
||
- ✅ `docker/backend.Dockerfile` - 后端镜像构建
|
||
- ✅ `docker/frontend.Dockerfile` - 前端镜像构建（Nginx）
|
||
- ✅ `.dockerignore` - 优化构建速度
|
||
|
||
### 2. npm 配置（中国大陆优化）
|
||
- ✅ `server/.npmrc` - 后端 npm 镜像源
|
||
- ✅ `client/.npmrc` - 前端 npm 镜像源
|
||
- ✅ 自动 fallback 机制（阿里云 → 腾讯云 → 华为云）
|
||
|
||
### 3. 构建脚本
|
||
- ✅ `build-docker.ps1` - PowerShell 构建脚本
|
||
- ✅ `build-docker.bat` - CMD 构建脚本
|
||
- ✅ `build-docker.sh` - Linux/Mac 构建脚本
|
||
- ✅ `publish-docker.bat` - Docker Hub 发布脚本
|
||
|
||
### 4. 开发工具
|
||
- ✅ `start-dev.ps1` - 本地开发启动脚本
|
||
- ✅ `start-dev.bat` - CMD 开发启动脚本
|
||
- ✅ `switch-npm-mirror.bat` - 切换 npm 镜像源
|
||
- ✅ `test-npm-registry.bat` - 测试 npm 连接
|
||
|
||
### 5. 文档
|
||
- ✅ `README.md` - 项目介绍
|
||
- ✅ `USER-GUIDE.md` - 用户快速开始指南
|
||
- ✅ `DISTRIBUTION-GUIDE.md` - 分发指南
|
||
- ✅ `DISTRIBUTION-STRATEGY.md` - 分发策略详解
|
||
- ✅ `TROUBLESHOOTING.md` - 故障排除
|
||
- ✅ `LOCAL-DEV-GUIDE.md` - 本地开发指南
|
||
- ✅ `DOCKER-BUILD-GUIDE.md` - Docker 构建指南
|
||
|
||
---
|
||
|
||
## 🎯 分发方式选择
|
||
|
||
### 方式 1：GitHub 仓库（推荐用于开源）
|
||
|
||
**包含文件：**
|
||
```
|
||
sillytavern-repalice/
|
||
├── docker/
|
||
│ ├── backend.Dockerfile
|
||
│ └── frontend.Dockerfile
|
||
├── server/ # 后端源码
|
||
├── client/ # 前端源码
|
||
├── shared/ # 共享模块
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
├── .dockerignore
|
||
├── package.json
|
||
├── USER-GUIDE.md # ⭐ 用户必读
|
||
├── README.md
|
||
└── ...其他配置文件
|
||
```
|
||
|
||
**用户操作：**
|
||
```bash
|
||
git clone <repo-url>
|
||
cd sillytavern-repalice
|
||
cp .env.example .env
|
||
# 编辑 .env
|
||
docker-compose up -d
|
||
```
|
||
|
||
**优点：**
|
||
- ✅ 完全透明
|
||
- ✅ 用户可以自定义
|
||
- ✅ 便于协作开发
|
||
|
||
---
|
||
|
||
### 方式 2：Docker Hub（推荐用于正式发布）
|
||
|
||
**步骤 1：推送镜像到 Docker Hub**
|
||
|
||
```bash
|
||
# 登录
|
||
docker login
|
||
|
||
# 运行发布脚本
|
||
.\publish-docker.bat
|
||
# 输入版本号，例如：1.0.0
|
||
```
|
||
|
||
**步骤 2：提供给用户的文件**
|
||
|
||
创建简化的分发包：
|
||
```
|
||
sillytavern-repalice-release/
|
||
├── docker-compose.prod.yml # 重命名为 docker-compose.yml
|
||
├── .env.example
|
||
├── USER-GUIDE.md # ⭐ 用户必读
|
||
└── README.md
|
||
```
|
||
|
||
修改 `docker-compose.prod.yml` 中的镜像地址：
|
||
```yaml
|
||
services:
|
||
backend:
|
||
image: yourusername/sillytavern-repalice-backend:latest
|
||
|
||
frontend:
|
||
image: yourusername/sillytavern-repalice-frontend:latest
|
||
```
|
||
|
||
**用户操作：**
|
||
```bash
|
||
# 下载分发包
|
||
# 解压
|
||
|
||
cp .env.example .env
|
||
# 编辑 .env
|
||
|
||
docker-compose up -d
|
||
```
|
||
|
||
**优点：**
|
||
- ✅ 启动速度快（无需构建）
|
||
- ✅ 用户操作简单
|
||
- ✅ 版本管理清晰
|
||
|
||
---
|
||
|
||
### 方式 3：离线镜像（内网环境）
|
||
|
||
**步骤 1：导出镜像**
|
||
|
||
```bash
|
||
# 构建
|
||
docker-compose build
|
||
|
||
# 导出
|
||
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-offline/
|
||
├── sillytavern-images.tar.gz
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
├── USER-GUIDE.md
|
||
└── import-images.bat/psh # 导入脚本
|
||
```
|
||
|
||
**用户操作：**
|
||
```bash
|
||
# 解压镜像
|
||
tar -xzf sillytavern-images.tar.gz
|
||
|
||
# 导入
|
||
docker load -i backend.tar
|
||
docker load -i frontend.tar
|
||
|
||
# 配置
|
||
cp .env.example .env
|
||
|
||
# 启动
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 分发前检查清单
|
||
|
||
### 代码检查
|
||
- [ ] 所有功能测试通过
|
||
- [ ] 没有硬编码的敏感信息
|
||
- [ ] `.env` 在 `.gitignore` 中
|
||
- [ ] `node_modules` 在 `.dockerignore` 中
|
||
|
||
### Docker 检查
|
||
- [ ] `docker-compose up -d` 能正常启动
|
||
- [ ] 前后端都能正常访问
|
||
- [ ] 数据持久化正常工作
|
||
- [ ] 日志输出清晰
|
||
|
||
### 文档检查
|
||
- [ ] `USER-GUIDE.md` 完整准确
|
||
- [ ] `.env.example` 包含所有必要配置
|
||
- [ ] README 指向正确的文档
|
||
- [ ] 常见问题已覆盖
|
||
|
||
### 镜像检查（如使用 Docker Hub）
|
||
- [ ] 镜像可以成功推送
|
||
- [ ] 镜像可以从 Docker Hub 拉取
|
||
- [ ] 版本号标签正确
|
||
- [ ] `latest` 标签指向最新版本
|
||
|
||
---
|
||
|
||
## 🚀 快速分发流程
|
||
|
||
### 对于开发者
|
||
|
||
```bash
|
||
# 1. 确保代码最新
|
||
git add .
|
||
git commit -m "Release version 1.0.0"
|
||
git push
|
||
|
||
# 2. 构建并推送镜像（可选）
|
||
.\publish-docker.bat
|
||
# 输入：1.0.0
|
||
|
||
# 3. 创建 Release Tag
|
||
git tag v1.0.0
|
||
git push origin v1.0.0
|
||
```
|
||
|
||
### 对于用户
|
||
|
||
**从 GitHub：**
|
||
```bash
|
||
git clone https://github.com/yourusername/sillytavern-repalice.git
|
||
cd sillytavern-repalice
|
||
cp .env.example .env
|
||
# 编辑 .env
|
||
docker-compose up -d
|
||
```
|
||
|
||
**从 Docker Hub：**
|
||
```bash
|
||
# 下载 docker-compose.prod.yml 和 .env.example
|
||
# 重命名 docker-compose.prod.yml 为 docker-compose.yml
|
||
cp .env.example .env
|
||
# 编辑 .env
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 方案对比
|
||
|
||
| 特性 | GitHub | Docker Hub | 离线镜像 |
|
||
|------|--------|------------|----------|
|
||
| 设置难度 | ⭐ | ⭐⭐ | ⭐⭐⭐ |
|
||
| 启动速度 | 🐌 慢 | ⚡ 快 | ⚡ 快 |
|
||
| 文件大小 | 🟢 小 | 🟡 中 | 🔴 大 |
|
||
| 可定制性 | ✅ 高 | ❌ 低 | ❌ 低 |
|
||
| 适用场景 | 开源/开发 | 正式发布 | 内网 |
|
||
|
||
---
|
||
|
||
## 💡 最佳实践建议
|
||
|
||
### 1. 同时提供多种方式
|
||
- GitHub 仓库（主要）
|
||
- Docker Hub 镜像（可选）
|
||
- 离线包（按需）
|
||
|
||
### 2. 文档优先
|
||
- `USER-GUIDE.md` 必须清晰简洁
|
||
- 提供截图或视频教程
|
||
- 常见问题单独列出
|
||
|
||
### 3. 简化用户操作
|
||
- 提供一键启动脚本
|
||
- 默认配置尽可能合理
|
||
- 错误提示友好清晰
|
||
|
||
### 4. 版本管理
|
||
- 使用语义化版本号
|
||
- CHANGELOG 记录变更
|
||
- 保持向后兼容
|
||
|
||
---
|
||
|
||
## 🎯 推荐方案
|
||
|
||
**对于大多数项目，推荐组合使用：**
|
||
|
||
1. **主要分发**：GitHub 仓库
|
||
- 完整源码
|
||
- 详细文档
|
||
- 适合开发和定制
|
||
|
||
2. **快速部署**：Docker Hub 镜像
|
||
- 一键启动
|
||
- 适合生产环境
|
||
- 定期更新
|
||
|
||
3. **特殊需求**：离线镜像
|
||
- 内网部署
|
||
- 安全要求高的环境
|
||
|
||
---
|
||
|
||
## 📞 用户支持
|
||
|
||
提供以下支持渠道：
|
||
- 📖 完整文档（USER-GUIDE.md）
|
||
- 🐛 Issue 追踪
|
||
- 💬 讨论区
|
||
- 📧 联系方式
|
||
|
||
---
|
||
|
||
**祝您分发顺利！** 🎉
|
||
|
||
如有问题，请参考：
|
||
- [用户指南](USER-GUIDE.md)
|
||
- [故障排除](TROUBLESHOOTING.md)
|
||
- [分发策略](DISTRIBUTION-STRATEGY.md)
|