# 开始使用

## 前提条件

- **Node.js** (推荐 v18 或更高版本)
- **npm** (v9 或更高版本) 或 **yarn**
- **Python 3.8+** (用于 yt-dlp 和 PO Token 提供者)
- **yt-dlp** (通过 pip/pipx 安装)
- **Docker** (可选，用于容器化部署)

## 安装

### 1. 克隆仓库

```bash
git clone https://github.com/franklioxygen/mytube.git
cd mytube
```

### 2. 安装依赖

您可以使用一条命令安装根目录、前端和后端的所有依赖：

```bash
npm run install:all
```

或者手动安装：

```bash
npm install
cd frontend && npm install
cd ../backend && npm install
```

**注意**: 后端安装会自动构建 `bgutil-ytdlp-pot-provider` 服务器。但是，您必须确保在环境中安装了 `yt-dlp` 和 `bgutil-ytdlp-pot-provider` Python 插件：

```bash
# 安装 yt-dlp 和插件
pip install yt-dlp bgutil-ytdlp-pot-provider

# 或使用 pipx (推荐，用于隔离)
pipx install yt-dlp
pipx inject yt-dlp bgutil-ytdlp-pot-provider
```

### 3. 配置环境变量

#### 后端配置

在 `backend/` 目录中创建 `.env` 文件：

```env
PORT=5551
```

默认数据与上传路径位于 `backend/data` 和 `backend/uploads`（相对于后端工作目录）。

#### 前端配置

在 `frontend/` 目录中创建 `.env` 文件：

```env
VITE_API_URL=/api
VITE_BACKEND_URL=
```

项目提供 `backend/.env.example`，请复制为 `backend/.env` 并按需调整。前端已提供 `frontend/.env`，如需覆盖默认值请使用 `frontend/.env.local`。

### 4. 数据库设置

应用程序使用 **SQLite** 和 **Drizzle ORM**。数据库将在首次启动时自动创建和迁移：

- 数据库位置: `backend/data/mytube.db`
- 迁移在服务器启动时自动运行
- 如果您有旧的 JSON 数据，可以使用设置页面或 API 端点进行迁移

## 运行应用

### 开发模式

从根目录启动前端和后端：

```bash
npm run dev
```

这将启动：

- **前端**: http://localhost:5556 (带热重载的 Vite 开发服务器)
- **后端 API**: http://localhost:5551 (带 nodemon 的 Express 服务器)

### 生产模式 (本地)

构建并以生产模式启动：

```bash
# 构建前端
npm run build

# 启动后端
cd backend
npm run start

# 在另一个终端预览前端构建
cd frontend
npm run preview
```

生产环境建议参考 [Docker 部署指南](docker-guide.md)。

根目录的 `npm run start` 为便捷命令，会同时运行后端启动脚本和前端开发服务器。

### 单独运行服务

您也可以单独运行服务：

```bash
# 仅后端
cd backend
npm run dev        # 开发模式
npm run start      # 生产模式

# 仅前端
cd frontend
npm run dev        # 开发模式
npm run preview    # 预览生产构建
```

## 可用脚本

从根目录：

```bash
npm run dev          # 以开发模式启动前端和后端
npm run start        # 启动后端 + 前端开发服务器 (便捷)
npm run build        # 为生产环境构建前端
npm run install:all  # 安装根目录、前端和后端的依赖
npm run test         # 运行前后端测试
npm run test:frontend # 运行前端测试
npm run test:backend  # 运行后端测试
```

后端特定脚本 (从 `backend/` 目录)：

```bash
npm run dev          # 使用 nodemon 启动后端 (自动重载)
npm run start        # 以生产模式启动后端
npm run build        # 将 TypeScript 编译为 JavaScript
npm run test         # 使用 Vitest 运行测试
npm run test:coverage # 运行测试并生成覆盖率报告
npm run generate     # 使用 Drizzle Kit 生成数据库迁移
npm run reset-password # 使用脚本重置管理员密码
```

前端特定脚本 (从 `frontend/` 目录)：

```bash
npm run dev          # 启动 Vite 开发服务器
npm run build        # 为生产环境构建
npm run preview      # 预览生产构建
npm run lint         # 运行 ESLint
npm run test         # 使用 Vitest 运行测试
npm run test:coverage # 运行测试并生成覆盖率报告
```

## 首次设置

1. **访问应用**: 在浏览器中打开 http://localhost:5556

2. **设置登录保护** (可选):

   - 转到设置 → 安全
   - 启用登录并设置管理员密码
   - 可选：注册通行密钥 (WebAuthn)

3. **配置下载设置**:

   - 转到设置 → 下载设置
   - 设置并发下载限制
   - 配置下载质量偏好

4. **上传 Cookies** (可选，用于年龄限制/会员内容):

   - 转到设置 → Cookie 设置
   - 上传您的 `cookies.txt` 文件

5. **配置云存储** (可选):

   - 转到设置 → 云盘设置
   - 启用"启用自动保存到云盘"
   - 输入您的 OpenList/Alist API URL (例如: `https://your-alist-instance.com/api/fs/put`)
   - 输入您的 API 令牌
   - 可选：设置用于直接文件访问的公共 URL
   - 设置上传路径 (例如: `/mytube-uploads`)
   - 测试连接以验证设置
   - 注意：启用后，视频将在下载后自动上传到云存储，本地文件将被删除

6. **配置访客用户** (可选):

   - 转到设置 → 安全
   - 启用“访客用户”以获得只读访问
   - 为访客角色设置登录密码

7. **开始下载**:
   - 在下载输入框中输入视频 URL
   - 支持的平台: YouTube, Bilibili, MissAV 以及所有 yt-dlp 支持的网站

## 架构概述

### 后端

- **框架**: Express.js with TypeScript
- **数据库**: SQLite with Drizzle ORM
- **架构**: 分层 (路由 → 控制器 → 服务 → 数据库)
- **下载器**: 用于平台特定实现的抽象基类模式

### 前端

- **框架**: React 19 with TypeScript
- **构建工具**: Vite
- **UI 库**: Material-UI (MUI)
- **状态管理**: React Context API
- **路由**: React Router v7

### 关键特性

- **模块化存储服务**: 拆分为专注的模块以提高可维护性
- **下载队列管理**: 支持队列的并发下载
- **视频下载跟踪**: 防止重复下载
- **订阅系统**: 从订阅的频道自动下载
- **数据库迁移**: 启动时自动更新模式

## 故障排除

### 数据库问题

- 如果遇到数据库错误，请检查 `backend/data/` 目录是否存在且可写
- 要重置数据库，请删除 `backend/data/mytube.db` 并重启服务器

### 下载问题

- 确保 `yt-dlp` 已安装且可在您的 PATH 中访问
- 检查是否安装了 `bgutil-ytdlp-pot-provider` 插件
- 验证网络连接和防火墙设置

### 端口冲突

- 如果端口 5551 或 5556 被占用，请修改 PORT 环境变量
- 相应地更新前端 `VITE_API_URL` 和 `VITE_BACKEND_URL`

### 文件监视器限制（ENOSPC 错误）

如果在运行前端开发服务器时遇到 `ENOSPC: System limit for number of file watchers reached` 错误：

**注意：** 项目的 `vite.config.js` 已配置为使用基于轮询的文件监视作为解决方案，这应该能在大多数情况下防止此错误。如果您仍然遇到此问题，请尝试以下解决方案：

**在 Linux（主机系统）上：**

```bash
# 检查当前限制
cat /proc/sys/fs/inotify/max_user_watches

# 增加限制（临时，重启后失效）
sudo sysctl fs.inotify.max_user_watches=524288

# 永久设置
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

**在 Docker 中：**
在 `docker-compose.yml` 的前端服务下添加：

```yaml
services:
  frontend:
    sysctls:
      - fs.inotify.max_user_watches=524288
```

或使用以下命令运行容器：

```bash
docker run --sysctl fs.inotify.max_user_watches=524288 ...
```

**替代方案：配置 Vite 使用轮询（本项目已配置）：**

`vite.config.js` 文件包含一个使用轮询而非原生文件监视器的监视配置，这完全绕过了 inotify 限制：

```js
server: {
  watch: {
    usePolling: true,
    interval: 2000,
    ignored: ['/node_modules/']
  }
}
```

这已在项目中配置，因此不应出现此错误。如果您使用自定义 Vite 配置，请确保包含此配置。

## 下一步

- 阅读 [API 端点](api-endpoints.md) 文档
- 查看 [目录结构](directory-structure.md) 了解代码组织
- 查看 [Docker 部署指南](docker-guide.md) 了解生产部署