# 🚀 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）