369 lines
7.0 KiB
Markdown
369 lines
7.0 KiB
Markdown
# 🚀 SillyTavern Repalice - 用户快速开始指南
|
||
|
||
欢迎使用 SillyTavern Repalice！这是一个基于 AI 的角色扮演聊天应用。
|
||
|
||
## 📋 前置要求
|
||
|
||
在开始之前，请确保您的系统已安装：
|
||
|
||
- ✅ [Docker Desktop](https://www.docker.com/products/docker-desktop/)（包含 Docker Compose）
|
||
|
||
**检查安装：**
|
||
```bash
|
||
docker --version
|
||
docker-compose --version
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 快速开始（3 步搞定）
|
||
|
||
### 步骤 1：获取项目文件
|
||
|
||
**方式 A：从 GitHub 克隆（推荐）**
|
||
```bash
|
||
git clone https://github.com/yourusername/sillytavern-repalice.git
|
||
cd sillytavern-repalice
|
||
```
|
||
|
||
**方式 B：下载 ZIP 包**
|
||
1. 访问项目主页
|
||
2. 点击 "Code" → "Download ZIP"
|
||
3. 解压到任意目录
|
||
|
||
### 步骤 2：配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，填入您的 API 密钥
|
||
# Windows: notepad .env
|
||
# Mac/Linux: nano .env
|
||
```
|
||
|
||
**必填配置示例：**
|
||
```env
|
||
# OpenAI API 密钥（二选一）
|
||
OPENAI_API_KEY=sk-your-openai-key-here
|
||
|
||
# 或者 Anthropic API 密钥
|
||
ANTHROPIC_API_KEY=sk-ant-your-key-here
|
||
|
||
# 其他配置（可保持默认）
|
||
NODE_ENV=production
|
||
PORT=3000
|
||
DATA_DIR=./data
|
||
```
|
||
|
||
> 💡 **提示**：您可以在 [OpenAI Platform](https://platform.openai.com/api-keys) 或 [Anthropic Console](https://console.anthropic.com/) 获取 API 密钥。
|
||
|
||
### 步骤 3：启动应用
|
||
|
||
```bash
|
||
# 一键启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看启动日志（可选）
|
||
docker-compose logs -f
|
||
```
|
||
|
||
**等待约 1-2 分钟**，直到看到类似输出：
|
||
```
|
||
backend | 🚀 Server is running on http://localhost:3000
|
||
frontend | /docker-entrypoint.sh: Configuration complete; ready for start up
|
||
```
|
||
|
||
---
|
||
|
||
## 🌐 访问应用
|
||
|
||
启动成功后，在浏览器中打开：
|
||
|
||
- **🎨 前端界面**: http://localhost:23337
|
||
- **🔧 后端 API**: http://localhost:3000
|
||
|
||
**首次使用**：
|
||
1. 打开 http://localhost:23337
|
||
2. 创建您的第一个角色卡
|
||
3. 开始聊天！
|
||
|
||
---
|
||
|
||
## ⏹️ 停止应用
|
||
|
||
```bash
|
||
# 停止所有服务
|
||
docker-compose down
|
||
|
||
# 停止并删除数据（谨慎使用！）
|
||
docker-compose down -v
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 更新到最新版本
|
||
|
||
```bash
|
||
# 拉取最新代码
|
||
git pull
|
||
|
||
# 重新构建并启动
|
||
docker-compose up -d --build
|
||
|
||
# 或者如果使用预构建镜像
|
||
docker-compose pull
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 常用命令
|
||
|
||
### 查看服务状态
|
||
```bash
|
||
docker-compose ps
|
||
```
|
||
|
||
### 查看日志
|
||
```bash
|
||
# 查看所有日志
|
||
docker-compose logs -f
|
||
|
||
# 只查看后端日志
|
||
docker-compose logs -f backend
|
||
|
||
# 只查看前端日志
|
||
docker-compose logs -f frontend
|
||
|
||
# 查看最近 100 行
|
||
docker-compose logs --tail=100
|
||
```
|
||
|
||
### 重启服务
|
||
```bash
|
||
# 重启所有服务
|
||
docker-compose restart
|
||
|
||
# 重启单个服务
|
||
docker-compose restart backend
|
||
docker-compose restart frontend
|
||
```
|
||
|
||
### 进入容器（调试用）
|
||
```bash
|
||
# 进入后端容器
|
||
docker-compose exec backend sh
|
||
|
||
# 进入前端容器
|
||
docker-compose exec frontend sh
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 数据存储
|
||
|
||
所有数据存储在 `./data` 目录：
|
||
|
||
```
|
||
data/
|
||
├── characters/ # 角色卡
|
||
├── chats/ # 聊天记录
|
||
├── worldinfo/ # 世界书
|
||
├── presets/ # 预设配置
|
||
└── workflows/ # 工作流
|
||
```
|
||
|
||
**备份数据：**
|
||
```bash
|
||
# 压缩备份
|
||
tar -czf backup-$(date +%Y%m%d).tar.gz ./data
|
||
|
||
# Windows PowerShell
|
||
Compress-Archive -Path .\data -DestinationPath backup-$(Get-Date -Format yyyyMMdd).zip
|
||
```
|
||
|
||
**恢复数据：**
|
||
```bash
|
||
# 解压恢复
|
||
tar -xzf backup-20260426.tar.gz
|
||
|
||
# Windows PowerShell
|
||
Expand-Archive -Path backup-20260426.zip -DestinationPath .
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 常见问题
|
||
|
||
### ❓ 端口被占用怎么办？
|
||
|
||
**错误信息**：`port is already allocated`
|
||
|
||
**解决方案**：修改 `docker-compose.yml` 中的端口映射
|
||
|
||
```yaml
|
||
services:
|
||
backend:
|
||
ports:
|
||
- "8081:3000" # 将后端改为 8081 端口
|
||
|
||
frontend:
|
||
ports:
|
||
- "23338:80" # 将前端改为 23338 端口
|
||
```
|
||
|
||
然后重新启动：
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
访问地址变为：
|
||
- 前端：http://localhost:23338
|
||
- 后端：http://localhost:8081
|
||
|
||
---
|
||
|
||
### ❓ 容器启动失败怎么办？
|
||
|
||
**步骤 1：查看日志**
|
||
```bash
|
||
docker-compose logs backend
|
||
docker-compose logs frontend
|
||
```
|
||
|
||
**步骤 2：检查常见原因**
|
||
- `.env` 文件是否正确配置
|
||
- 端口是否被占用
|
||
- Docker Desktop 是否正常运行
|
||
|
||
**步骤 3：重新构建**
|
||
```bash
|
||
docker-compose down
|
||
docker-compose build --no-cache
|
||
docker-compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
### ❓ 如何修改配置？
|
||
|
||
**修改环境变量：**
|
||
1. 编辑 `.env` 文件
|
||
2. 重启服务：`docker-compose restart`
|
||
|
||
**修改 Docker 配置：**
|
||
1. 编辑 `docker-compose.yml`
|
||
2. 重新启动：`docker-compose up -d`
|
||
|
||
---
|
||
|
||
### ❓ 数据丢失了怎么办？
|
||
|
||
**检查 data 目录：**
|
||
```bash
|
||
ls -la ./data
|
||
```
|
||
|
||
**如果 data 目录为空：**
|
||
- 可能是权限问题
|
||
- 确保 Docker Desktop 有访问该目录的权限
|
||
|
||
**恢复备份：**
|
||
```bash
|
||
# 如果有备份，解压恢复
|
||
tar -xzf backup-20260426.tar.gz
|
||
```
|
||
|
||
---
|
||
|
||
### ❓ 如何完全卸载？
|
||
|
||
```bash
|
||
# 1. 停止并删除容器
|
||
docker-compose down -v
|
||
|
||
# 2. 删除镜像
|
||
docker rmi sillytavern-repalice-backend sillytavern-repalice-frontend
|
||
|
||
# 3. 删除数据（谨慎！）
|
||
rm -rf ./data
|
||
|
||
# 4. 删除项目文件
|
||
cd ..
|
||
rm -rf sillytavern-repalice
|
||
```
|
||
|
||
---
|
||
|
||
## 🆘 获取帮助
|
||
|
||
### 文档资源
|
||
- 📖 [项目 README](README.md)
|
||
- 📖 [分发指南](DISTRIBUTION-GUIDE.md)
|
||
- 📖 [故障排除](TROUBLESHOOTING.md)
|
||
|
||
### 社区支持
|
||
- 🐛 [提交 Issue](https://github.com/yourusername/sillytavern-repalice/issues)
|
||
- 💬 [讨论区](https://github.com/yourusername/sillytavern-repalice/discussions)
|
||
|
||
### 提供问题信息
|
||
报告问题时，请包含：
|
||
```bash
|
||
# 系统信息
|
||
docker --version
|
||
docker-compose --version
|
||
uname -a # Linux/Mac
|
||
ver # Windows
|
||
|
||
# 日志信息
|
||
docker-compose logs --tail=100 > logs.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 🎉 开始使用
|
||
|
||
现在您已经成功部署了 SillyTavern Repalice！
|
||
|
||
**下一步**：
|
||
1. 访问 http://localhost:23337
|
||
2. 创建您的第一个 AI 角色
|
||
3. 享受聊天的乐趣！
|
||
|
||
**祝您使用愉快！** 🚀
|
||
|
||
---
|
||
|
||
## 📝 附录
|
||
|
||
### 环境变量完整说明
|
||
|
||
| 变量名 | 说明 | 默认值 | 必填 |
|
||
|--------|------|--------|------|
|
||
| `OPENAI_API_KEY` | OpenAI API 密钥 | - | 是* |
|
||
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | - | 是* |
|
||
| `NODE_ENV` | 运行环境 | `production` | 否 |
|
||
| `PORT` | 后端端口 | `3000` | 否 |
|
||
| `DATA_DIR` | 数据目录 | `./data` | 否 |
|
||
| `FRONTEND_URL` | 前端地址 | `http://localhost:23337` | 否 |
|
||
| `VITE_API_URL` | API 地址 | `http://localhost:3000/api` | 否 |
|
||
|
||
*至少需要配置一个 LLM API 密钥
|
||
|
||
### 系统要求
|
||
|
||
| 项目 | 最低配置 | 推荐配置 |
|
||
|------|----------|----------|
|
||
| CPU | 2 核心 | 4 核心 |
|
||
| 内存 | 2 GB | 4 GB |
|
||
| 磁盘 | 5 GB | 10 GB |
|
||
| 操作系统 | Windows 10 / macOS 10.15 / Linux | 最新版本 |
|
||
|
||
### 网络要求
|
||
|
||
确保以下域名可访问：
|
||
- `registry.npmmirror.com`（中国大陆 npm 镜像）
|
||
- `hub.docker.com`（Docker Hub）
|
||
- `api.openai.com` 或 `api.anthropic.com`（LLM API）
|