6.6 KiB
6.6 KiB
📦 项目分发清单
✅ 已完成配置
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
└── ...其他配置文件
用户操作：
git clone <repo-url>
cd sillytavern-repalice
cp .env.example .env
# 编辑 .env
docker-compose up -d
优点：
- ✅ 完全透明
- ✅ 用户可以自定义
- ✅ 便于协作开发
方式 2：Docker Hub（推荐用于正式发布）
步骤 1：推送镜像到 Docker Hub
# 登录
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 中的镜像地址：
services:
backend:
image: yourusername/sillytavern-repalice-backend:latest
frontend:
image: yourusername/sillytavern-repalice-frontend:latest
用户操作：
# 下载分发包
# 解压
cp .env.example .env
# 编辑 .env
docker-compose up -d
优点：
- ✅ 启动速度快（无需构建）
- ✅ 用户操作简单
- ✅ 版本管理清晰
方式 3：离线镜像（内网环境）
步骤 1：导出镜像
# 构建
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 # 导入脚本
用户操作：
# 解压镜像
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标签指向最新版本
🚀 快速分发流程
对于开发者
# 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：
git clone https://github.com/yourusername/sillytavern-repalice.git
cd sillytavern-repalice
cp .env.example .env
# 编辑 .env
docker-compose up -d
从 Docker Hub：
# 下载 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 记录变更
- 保持向后兼容
🎯 推荐方案
对于大多数项目，推荐组合使用：
-
主要分发：GitHub 仓库
- 完整源码
- 详细文档
- 适合开发和定制
-
快速部署：Docker Hub 镜像
- 一键启动
- 适合生产环境
- 定期更新
-
特殊需求：离线镜像
- 内网部署
- 安全要求高的环境
📞 用户支持
提供以下支持渠道：
- 📖 完整文档（USER-GUIDE.md）
- 🐛 Issue 追踪
- 💬 讨论区
- 📧 联系方式
祝您分发顺利！ 🎉
如有问题，请参考：