dysync/docs/本地启动指南.md

# dysync.net 本地启动指南

## 📋 前置要求

### 1. 安装 .NET 6.0 SDK

**macOS 安装方式：**

```bash
# 方式一：使用 Homebrew（推荐）
brew install --cask dotnet-sdk

# 方式二：手动下载安装
# 访问 https://dotnet.microsoft.com/download/dotnet/6.0
# 下载 macOS 版本的 .NET 6.0 SDK 并安装
```

**验证安装：**
```bash
dotnet --version
# 应该显示类似：6.0.xxx
```

### 2. 安装 Node.js（已安装 ✅）

您已安装 Node.js v24.1.0，满足要求。

**推荐使用 pnpm（项目使用 pnpm-lock.yaml）：**
```bash
npm install -g pnpm
```

---

## 🚀 启动步骤

### 第一步：安装前端依赖

```bash
cd app
pnpm install
# 或者使用 yarn
# yarn install
```

### 第二步：启动后端服务

**打开第一个终端窗口：**

```bash
# 回到项目根目录
cd /Users/gaotu/WebstormProjects/dysync.net

# 还原 NuGet 包（首次运行）
dotnet restore

# 启动后端服务（开发模式）
dotnet run

# 或者指定端口（如果需要）
dotnet run --urls "http://localhost:10101"
```

**后端启动成功后：**
- ✅ 后端 API 运行在：`http://localhost:10101`
- ✅ Swagger 文档：`http://localhost:10101/swagger`
- ✅ 数据库会自动创建在：`db/dy.sqlite`
- ✅ 日志文件会生成在：`logs/` 目录

### 第三步：启动前端开发服务器

**打开第二个终端窗口：**

```bash
cd app

# 启动前端开发服务器
pnpm dev
# 或者
yarn dev
```

**前端启动成功后：**
- ✅ 前端运行在：`http://localhost:8001`
- ✅ 会自动代理 `/api` 请求到后端 `http://localhost:10101`

---

## 🔑 首次登录

1. 访问：`http://localhost:8001`
2. 默认账号：`douyin`
3. 默认密码：`douyin2025`

> ⚠️ **安全提示**：登录后请立即修改密码！

---

## 📁 目录结构说明

```
dysync.net/
├── db/                    # SQLite 数据库目录（自动创建）
│   └── dy.sqlite         # 数据库文件
├── logs/                  # 日志文件目录（自动创建）
│   ├── log-debug-*.txt   # 调试日志
│   └── log-error-*.txt   # 错误日志
├── app/                   # 前端项目
│   ├── dist/             # 前端构建产物（生产环境）
│   └── src/              # 前端源码
└── appsettings.json      # 后端配置文件
```

---

## ⚙️ 配置说明

### 后端配置 (`appsettings.json`)

```json
{
  "dbconn": "",           // SQLite 无需配置，自动创建
  "dbtype": "Sqlite"      // 数据库类型
}
```

### 前端配置 (`app/.env.development`)

```env
VITE_API_URL=http://localhost:10101
```

---

## 🐛 常见问题排查

### 1. 后端启动失败

**问题：端口被占用**
```bash
# macOS 查看端口占用
lsof -i :10101

# 杀死占用进程
kill -9 <PID>
```

**问题：数据库权限错误**
```bash
# 确保 db 目录有写权限
chmod 755 db
```

### 2. 前端启动失败

**问题：依赖安装失败**
```bash
# 清除缓存重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

**问题：API 请求失败（404）**
- 检查后端是否已启动
- 检查 `.env.development` 中的 `VITE_API_URL` 是否正确
- 检查浏览器控制台是否有 CORS 错误

### 3. 数据库相关

**数据库位置：**
- 开发环境：`项目根目录/db/dy.sqlite`
- 数据库会在首次启动时自动创建

**重置数据库：**
```bash
# 删除数据库文件（会丢失所有数据）
rm -rf db/dy.sqlite

# 重新启动后端，会自动创建新数据库
```

---

## 🎯 开发模式说明

### 开发环境特性

1. **热重载**：前端代码修改后自动刷新
2. **Swagger 文档**：`http://localhost:10101/swagger`
3. **详细日志**：所有日志输出到 `logs/` 目录
4. **数据库自动迁移**：模型变更后自动更新表结构

### 生产环境构建

**前端构建：**
```bash
cd app
pnpm build
# 构建产物在 app/dist/ 目录
```

**后端发布：**
```bash
dotnet publish -c Release -o ./publish
```

---

## 📝 下一步操作

1. ✅ 启动后端和前端服务
2. 🔐 使用默认账号登录
3. 🍪 在「抖音授权」页面配置 Cookie 和 sec_user_id
4. ⚙️ 在「系统配置」页面设置同步参数
5. 🎬 开始同步视频！

---

## 💡 提示

- **开发时建议**：保持两个终端窗口同时运行（后端 + 前端）
- **调试技巧**：查看 `logs/` 目录下的日志文件排查问题
- **API 测试**：使用 Swagger 文档测试接口功能