快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• Dockerfile
• docker-compose.dev.yml
• package.json
• .nvmrc
• src/lib/search-cache.ts
• src/lib/db.ts
• src/lib/time.ts
• src/lib/auth.ts
• src/lib/live.ts

LunaTV（MoonTV）是一个基于 Next.js 14 构建的跨平台影视聚合播放器，支持多资源搜索、在线播放、收藏同步和播放记录云端存储。该项目采用 Docker 容器化部署，提供 Kvrocks、Redis 和 Upstash 三种存储后端选项。

环境准备

系统要求

LunaTV 项目对运行环境有以下要求：

本地开发环境配置

项目使用 pnpm 作为包管理器，通过 corepack 进行版本管理。在 package.json:94 中明确指定了 packageManager: pnpm@10.14.0。

安装依赖的步骤：

bash
1# 启用 corepack 并激活 pnpm
2corepack enable && corepack prepare pnpm@latest --activate
3
4# 安装项目依赖
5pnpm install --frozen-lockfile

上述命令在 Docker 构建流程中也有体现，参见 Dockerfile:4-13。

核心依赖说明

项目的主要技术栈包括：

• 前端框架: Next.js 14（App Router）
• UI 框架: Tailwind CSS 3
• 播放器: ArtPlayer + HLS.js
• 存储客户端: Redis、Upstash Redis

完整的依赖列表参见 package.json:21-52。

本地开发启动

最短可运行路径（推荐）

使用 Docker Compose 是启动开发环境的最快方式。项目提供了完整的开发环境配置文件 docker-compose.dev.yml:1-39，包含 Redis 服务和应用服务。

bash
1# 克隆仓库
2git clone https://github.com/MoonTechLab/LunaTV.git
3cd LunaTV
4
5# 启动开发环境
6docker-compose -f docker-compose.dev.yml up -d
7
8# 查看日志
9docker-compose -f docker-compose.dev.yml logs -f app

启动成功后，应用将在 http://localhost:3000 提供服务，该端口配置参见 docker-compose.dev.yml:21-22。

开发环境配置说明

Docker Compose 开发环境包含以下服务配置：

Redis 服务配置了数据持久化卷 redis-data 和 AOF 持久化模式（--appendonly yes），参见 docker-compose.dev.yml:7-14。

环境变量配置

开发环境的关键环境变量在 docker-compose.dev.yml:26-36 中定义：

env
1# 存储类型配置
2NEXT_PUBLIC_STORAGE_TYPE=redis
3
4# Redis 连接地址（容器内部通过 service name 访问）
5REDIS_URL=redis://redis:6379
6
7# 管理员账号
8USERNAME=admin
9PASSWORD=admin123
10
11# 站点名称（可选）
12NEXT_PUBLIC_SITE_NAME=MoonTV

本地源码开发模式

如果需要在本地进行源码开发和调试，可以使用以下命令：

bash
1# 安装依赖
2pnpm install
3
4# 启动开发服务器
5pnpm dev

dev 脚本定义在 package.json:6，它会先执行 gen:manifest 生成 PWA manifest，然后启动 Next.js 开发服务器并监听 0.0.0.0 地址。

生产部署

部署方式概览

LunaTV 仅支持 Docker 或基于 Docker 的平台部署，参见 README.md:70-72。项目提供三种主要部署方式：

Docker 多阶段构建流程

项目的 Dockerfile 采用三阶段构建优化镜像大小和构建缓存利用率：

正在加载图表渲染器...

构建流程的关键步骤：

1. 依赖安装阶段（Dockerfile:1-13）：使用 node:20-alpine 基础镜像，通过 corepack 激活 pnpm 并安装依赖
2. 构建阶段（Dockerfile:15-29）：复制依赖和源代码，设置 DOCKER_ENV=true 环境变量，执行生产构建
3. 运行时阶段（Dockerfile:31-59）：创建非 root 用户，复制 standalone 输出和静态资源，暴露 3000 端口

Kvrocks 存储部署（推荐）

Kvrocks 是推荐的存储后端，提供更好的数据持久性保障。完整的 Docker Compose 配置参见 README.md:90-120：

yaml
1services:
2  moontv-core:
3    image: ghcr.io/moontechlab/lunatv:latest
4    container_name: moontv-core
5    restart: on-failure
6    ports:
7      - '3000:3000'
8    environment:
9      - USERNAME=admin
10      - PASSWORD=admin_password
11      - NEXT_PUBLIC_STORAGE_TYPE=kvrocks
12      - KVROCKS_URL=redis://moontv-kvrocks:6666
13    networks:
14      - moontv-network
15    depends_on:
16      - moontv-kvrocks
17      
18  moontv-kvrocks:
19    image: apache/kvrocks
20    container_name: moontv-kvrocks
21    restart: unless-stopped
22    volumes:
23      - kvrocks-data:/var/lib/kvrocks
24    networks:
25      - moontv-network
26
27networks:
28  moontv-network:
29    driver: bridge
30
31volumes:
32  kvrocks-data:

Upstash 云存储部署

对于无服务器架构或不想管理数据库的场景，可以使用 Upstash Redis 作为存储后端。配置示例参见 README.md:155-174：

yaml
1services:
2  moontv-core:
3    image: ghcr.io/moontechlab/lunatv:latest
4    container_name: moontv-core
5    restart: on-failure
6    ports:
7      - '3000:3000'
8    environment:
9      - USERNAME=admin
10      - PASSWORD=admin_password
11      - NEXT_PUBLIC_STORAGE_TYPE=upstash
12      - UPSTASH_URL=https://your-endpoint.upstash.io
13      - UPSTASH_TOKEN=your_token_here

环境变量完整列表

核心功能验证

服务启动验证

部署完成后，通过以下方式验证服务是否正常运行：

1. 访问 Web 界面：打开浏览器访问 http://localhost:3000（或配置的域名）
2. 检查容器状态：docker ps 确认容器处于 Up 状态
3. 查看日志输出：docker logs moontv-core 确认无错误信息

存储系统初始化验证

存储系统在应用启动时自动初始化。根据 src/lib/db.ts:25-31，系统根据 NEXT_PUBLIC_STORAGE_TYPE 环境变量创建对应的存储实例：

typescript
1switch (storageType) {
2  case 'upstash':
3    return new UpstashStorage();
4  case 'redis':
5    return new RedisStorage();
6  case 'kvrocks':
7    return new KvrocksStorage();
8  case 'localstorage':
9  default:
10    return null as unknown as IStorage;
11}

DbManager 类在构造时会自动触发数据迁移，包括数据结构迁移和密码哈希迁移，参见 src/lib/db.ts:53-66。

搜索缓存机制

搜索缓存采用内存 Map 实现，配置了 10 分钟 TTL 和最大 1000 条目限制，参见 src/lib/search-cache.ts:14-18：

typescript
1const SEARCH_CACHE_TTL_MS = 10 * 60 * 1000; // 10分钟
2const CACHE_CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5分钟清理一次
3const MAX_CACHE_SIZE = 1000; // 最大缓存条目数量

缓存系统采用惰性清理策略，在每次写入时检查是否需要执行清理，同时启动后台定时器进行周期性清理。

播放记录管理验证

播放记录功能通过 DbManager 类提供增删查接口，核心方法定义在 src/lib/db.ts:76-110：

登录管理员账号后，可以通过播放任意视频并刷新页面来验证播放记录是否正确保存和恢复。

常见问题与排错

问题 1：容器启动后无法访问 Web 界面

症状：容器状态正常，但浏览器无法访问 http://localhost:3000

排查步骤：

1. 确认端口映射配置正确：检查 docker-compose.yml 中 ports 配置是否为 '3000:3000'
2. 检查防火墙规则：确保宿主机 3000 端口未被防火墙阻止
3. 查看容器日志：docker logs moontv-core 检查是否有启动错误
4. 验证容器内服务：docker exec moontv-core wget -qO- http://localhost:3000 测试容器内部访问

常见原因：

• 端口被其他服务占用
• Docker 网络配置冲突
• 环境变量配置错误导致服务启动失败

问题 2：Redis/Kvrocks 连接失败

症状：日志中出现 ECONNREFUSED 或连接超时错误

排查步骤：

1. 确认存储服务已启动：docker ps | grep -E 'redis|kvrocks'
2. 检查网络配置：确保应用和存储服务在同一 Docker 网络中
3. 验证连接地址格式：
   • Kvrocks: redis://hostname:6666
   • Redis: redis://hostname:6379
4. 测试网络连通性：docker exec moontv-core ping moontv-kvrocks

解决方案：

• 检查 depends_on 配置确保依赖关系正确
• 使用 Docker 网络别名而非容器名
• 确认存储服务健康检查通过后再启动应用

问题 3：数据丢失或无法持久化

症状：重启容器后用户数据、播放记录丢失

排查步骤：

1. 检查 volumes 配置是否正确挂载
2. 确认 Redis 开启 AOF 持久化：redis-cli config get appendonly
3. 验证 Kvrocks 数据目录权限

解决方案：

对于 Redis，确保配置了持久化卷和 AOF 模式（参见 docker-compose.dev.yml:9）：

yaml
1command: redis-server --appendonly yes
2volumes:
3  - ./data:/data

对于 Kvrocks，确保数据卷挂载到 /var/lib/kvrocks（参见 README.md:111-112）。

问题 4：登录失败或认证无效

症状：使用正确的用户名密码无法登录

排查步骤：

1. 确认环境变量 USERNAME 和 PASSWORD 已正确设置
2. 检查浏览器控制台是否有 CORS 或 Cookie 相关错误
3. 清除浏览器缓存和 Cookie 后重试

解决方案：

• 重新设置环境变量并重启容器
• 确保访问的域名与 SITE_BASE 配置一致
• 检查是否启用了 HTTPS（某些浏览器在 HTTP 下限制 Cookie）

问题 5：构建失败或依赖安装错误

症状：执行 pnpm install 或 Docker 构建时失败

排查步骤：

1. 确认 Node.js 版本为 v20.10.0（参见 .nvmrc:1）
2. 确认 pnpm 版本为 10.14.0（参见 package.json:94）
3. 清除 pnpm 缓存：pnpm store prune

解决方案：

bash
1# 重置环境
2rm -rf node_modules pnpm-lock.yaml
3corepack prepare pnpm@10.14.0 --activate
4pnpm install

下一步建议

完成快速上手后，建议继续探索以下内容：

1. 配置订阅源：项目部署后为空壳，需要自行配置影视资源订阅源（参见 README.md:31）
2. 自定义站点信息：通过环境变量配置站点名称、公告等
3. 启用 PWA 功能：配置 HTTPS 以支持安装到桌面/主屏
4. 性能优化：根据实际负载调整缓存配置（参见 src/lib/search-cache.ts:14-18）
5. 安全加固：修改默认管理员密码，配置 HTTPS，限制容器资源

详细的配置选项和高级用法请参考项目的配置文件章节和环境变量文档。