315 lines
6.1 KiB
Markdown
315 lines
6.1 KiB
Markdown
# 快速开始指南
|
||
|
||
## 🚀 5分钟上手
|
||
|
||
### 前置检查
|
||
|
||
确保你的系统已安装:
|
||
- ✅ Node.js >= 20.x (`node -v`)
|
||
- ✅ npm >= 10.x (`npm -v`)
|
||
- ✅ Git (`git --version`)
|
||
|
||
### 步骤 1: 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd sillytavern-repalice
|
||
```
|
||
|
||
### 步骤 2: 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
这会安装所有工作区 (shared, server, client) 的依赖。
|
||
|
||
### 步骤 3: 配置环境变量
|
||
|
||
```bash
|
||
# 复制示例配置
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，填入你的 API 密钥
|
||
# Windows: notepad .env
|
||
# macOS/Linux: nano .env
|
||
```
|
||
|
||
最小配置示例:
|
||
```env
|
||
OPENAI_API_KEY=sk-your-openai-key
|
||
LLM_PROVIDER=openai
|
||
LLM_MODEL=gpt-4
|
||
```
|
||
|
||
### 步骤 4: 启动开发服务器
|
||
|
||
```bash
|
||
# 同时启动前后端（推荐）
|
||
npm run dev
|
||
```
|
||
|
||
或者分别启动:
|
||
```bash
|
||
# 终端 1: 启动后端
|
||
npm run dev:server
|
||
|
||
# 终端 2: 启动前端
|
||
npm run dev:client
|
||
```
|
||
|
||
### 步骤 5: 访问应用
|
||
|
||
打开浏览器访问:
|
||
- **前端**: http://localhost:5173
|
||
- **后端 API**: http://localhost:3000/api
|
||
|
||
## 🐳 Docker 部署
|
||
|
||
### 快速启动
|
||
|
||
```bash
|
||
# 构建并启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 查看运行状态
|
||
docker-compose ps
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
```
|
||
|
||
### 仅构建镜像
|
||
|
||
```bash
|
||
docker-compose build
|
||
```
|
||
|
||
### 数据持久化
|
||
|
||
Docker 会自动将数据挂载到 `./data` 目录:
|
||
```
|
||
sillytavern-repalice/
|
||
└── data/ # 此目录会包含所有持久化数据
|
||
├── characters/
|
||
├── chats/
|
||
├── worldinfo/
|
||
└── presets/
|
||
```
|
||
|
||
## 📂 项目结构速览
|
||
|
||
```
|
||
sillytavern-repalice/
|
||
├── shared/ # 🔗 前后端共享类型和 schemas
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ └── schemas/ # Zod 验证 schemas
|
||
│
|
||
├── server/ # 🖥️ 后端 NestJS
|
||
│ └── src/
|
||
│ ├── modules/ # 业务模块
|
||
│ ├── services/ # 业务逻辑
|
||
│ └── persistence/ # 数据持久化
|
||
│
|
||
├── client/ # 🎨 前端 Vue3
|
||
│ └── src/
|
||
│ ├── components/ # UI 组件
|
||
│ ├── stores/ # 状态管理
|
||
│ └── router/ # 路由配置
|
||
│
|
||
└── data/ # 💾 运行时生成的数据
|
||
```
|
||
|
||
## 🔧 常用命令
|
||
|
||
### 开发
|
||
|
||
```bash
|
||
npm run dev # 启动开发环境
|
||
npm run dev:server # 仅启动后端
|
||
npm run dev:client # 仅启动前端
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
npm run build # 构建所有项目
|
||
npm run build:server # 构建后端
|
||
npm run build:client # 构建前端
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
npm test # 运行所有测试
|
||
npm run lint # 代码检查
|
||
```
|
||
|
||
### Docker
|
||
|
||
```bash
|
||
npm run docker:up # 启动容器
|
||
npm run docker:down # 停止容器
|
||
npm run docker:build # 构建镜像
|
||
npm run docker:logs # 查看日志
|
||
```
|
||
|
||
## 🎯 第一个任务：创建角色卡
|
||
|
||
> ⚠️ 注意: 当前项目处于架构搭建阶段，UI 组件为占位符。以下流程展示预期的使用方式。
|
||
|
||
### 通过 API 创建角色
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/characters \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "艾莉丝",
|
||
"description": "一位勇敢的冒险者",
|
||
"personality": "开朗、勇敢、幽默",
|
||
"scenario": "在一个魔法世界中冒险",
|
||
"first_mes": "你好！我是艾莉丝，很高兴认识你！",
|
||
"mes_example": ""
|
||
}'
|
||
```
|
||
|
||
### 导入 SillyTavern 角色卡
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/import/character \
|
||
-F "file=@/path/to/character.png"
|
||
```
|
||
|
||
## 🐛 故障排查
|
||
|
||
### 问题: 端口被占用
|
||
|
||
**错误**: `Error: listen EADDRINUSE: address already in use :::3000`
|
||
|
||
**解决**:
|
||
```bash
|
||
# Windows
|
||
netstat -ano | findstr :3000
|
||
taskkill /PID <PID> /F
|
||
|
||
# macOS/Linux
|
||
lsof -ti:3000 | xargs kill -9
|
||
```
|
||
|
||
或修改 `.env` 中的 `PORT` 变量。
|
||
|
||
### 问题: 依赖安装失败
|
||
|
||
**解决**:
|
||
```bash
|
||
# 清除缓存
|
||
npm cache clean --force
|
||
|
||
# 删除 node_modules
|
||
rm -rf node_modules server/node_modules client/node_modules shared/node_modules
|
||
|
||
# 重新安装
|
||
npm install
|
||
```
|
||
|
||
### 问题: TypeScript 编译错误
|
||
|
||
**解决**:
|
||
```bash
|
||
# 清除构建缓存
|
||
cd server && rm -rf dist
|
||
cd client && rm -rf dist
|
||
|
||
# 重新构建
|
||
npm run build
|
||
```
|
||
|
||
### 问题: Docker 容器无法启动
|
||
|
||
**解决**:
|
||
```bash
|
||
# 查看详细日志
|
||
docker-compose logs backend
|
||
docker-compose logs frontend
|
||
|
||
# 重建容器
|
||
docker-compose down
|
||
docker-compose build --no-cache
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 📚 学习资源
|
||
|
||
### 项目文档
|
||
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 详细架构设计
|
||
- [README.md](./README.md) - 项目概览
|
||
|
||
### 技术栈文档
|
||
- [NestJS 官方文档](https://docs.nestjs.com/)
|
||
- [Vue 3 官方文档](https://vuejs.org/)
|
||
- [Vercel AI SDK](https://sdk.vercel.ai/docs)
|
||
- [Zod 文档](https://zod.dev/)
|
||
- [Pinia 文档](https://pinia.vuejs.org/)
|
||
|
||
### SillyTavern 参考
|
||
- [SillyTavern 官方文档](https://st-docs.role.fun/)
|
||
- [角色卡规范 V2](https://github.com/malfoyslastname/character-card-spec-v2)
|
||
|
||
## 🤝 贡献指南
|
||
|
||
### 添加新功能
|
||
|
||
1. **定义类型** (shared/types/)
|
||
```typescript
|
||
// shared/types/my-feature.types.ts
|
||
export interface MyFeature {
|
||
id: string;
|
||
name: string;
|
||
}
|
||
```
|
||
|
||
2. **创建后端模块** (server/src/modules/my-feature/)
|
||
```typescript
|
||
// server/src/modules/my-feature/my-feature.module.ts
|
||
@Module({
|
||
controllers: [MyFeatureController],
|
||
providers: [MyFeatureService],
|
||
})
|
||
export class MyFeatureModule {}
|
||
```
|
||
|
||
3. **创建前端组件** (client/src/components/MyFeature/)
|
||
```vue
|
||
<!-- client/src/components/MyFeature/MyFeature.vue -->
|
||
<template>
|
||
<div>My Feature</div>
|
||
</template>
|
||
```
|
||
|
||
4. **注册模块**
|
||
- 在 `server/src/app.module.ts` 中添加后端模块
|
||
- 在 `client/src/router/index.ts` 中添加路由
|
||
|
||
### 提交 PR
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 开启 Pull Request
|
||
|
||
## 📞 获取帮助
|
||
|
||
- 📖 查阅 [ARCHITECTURE.md](./ARCHITECTURE.md)
|
||
- 🐛 提交 [GitHub Issue](../../issues)
|
||
- 💬 参与讨论 (如果有社区)
|
||
|
||
---
|
||
|
||
**祝你使用愉快！** 🎉
|
||
|
||
如有问题或建议，欢迎反馈。
|