Skip to content

一分钟搭建影视站,支持Docker等部署方式

feat(deploy): 支持通过 GHCR 发布镜像并统一版本管理

bestZweid7850ccba2c7
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..dfdfe19
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,22 @@
+# 依赖与构建产物:镜像内由 npm ci / next build 重新生成
+node_modules
+.next
+out
+tsconfig.tsbuildinfo
+
+# 版本控制与 CI
+.git
+.gitignore
+.github
+
+# 本地环境与日志
+.env
+.env*.local
+*.log
+
+# 文档与编排文件(不参与镜像构建)
+Dockerfile
+docker-compose.yml
+docs
+README.md
+LICENSE
diff --git a/.env.example b/.env.example
index 644f122..5c9ffe1 100644
--- a/.env.example
+++ b/.env.example
@@ -10,3 +10,7 @@ MAX_RETRIES=1
# 可选:调试
DEBUG=false
+
+# 可选:直接使用发布镜像(如 ghcr.io/xxx/libretv:2.0.0)时设置,
+# 不设置则用本地源码构建(tag 与 package.json 的 version 对应)
+# LIBRETV_IMAGE=
diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml
new file mode 100644
index 0000000..135657d
--- /dev/null
+++ b/.github/workflows/docker-publish.yml
@@ -0,0 +1,72 @@
+name: docker-publish
+
+# 推送版本 tag(如 v2.0.1)时自动构建并发布镜像到 GHCR;
+# 也可在 Actions 页面手动触发。
+# 无需配置任何 secrets:使用内置 GITHUB_TOKEN 推送 ghcr.io。
+
+on:
+ push:
+ tags:
+ - 'v*'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ packages: write
+
+env:
+ REGISTRY: ghcr.io
+
+jobs:
+ # 先跑类型检查与单测,避免把坏版本推成镜像
+ verify:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: npm
+ - run: npm ci
+ - run: npm run typecheck
+ - run: npm test
+
+ publish:
+ needs: verify
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ # GHCR 镜像名不允许大写,统一转小写(bestzwei/LibreTV → bestzwei/libretv)
+ - name: 计算镜像名
+ id: image
+ run: echo "name=${REGISTRY}/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+
+ - uses: docker/setup-qemu-action@v3
+ - uses: docker/setup-buildx-action@v3
+
+ - uses: docker/login-action@v3
+ with:
+ registry: ${{ env.REGISTRY }}
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ # tag v2.0.1 → 2.0.1 / 2.0 / latest 三个标签
+ - id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ${{ steps.image.outputs.name }}
+ tags: |
+ type=semver,pattern={{version}}
+ type=semver,pattern={{major}}.{{minor}}
+ type=raw,value=latest
+
+ - uses: docker/build-push-action@v6
+ with:
+ context: .
+ platforms: linux/amd64,linux/arm64
+ push: true
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
diff --git a/README.md b/README.md
index 5eef3fc..d9fcdd5 100644
--- a/README.md
+++ b/README.md
@@ -25,9 +25,20 @@ LibreTV 的 Next.js 重构版:免费在线视频聚合搜索与观看平台。
```bash
# 在 .env 中设置 PASSWORD
echo "PASSWORD=your-password" > .env
-docker compose up -d -b
+
+# 方式一:拉取发布镜像(零构建)
+docker compose pull && docker compose up -d
+
+# 方式二:源码构建
+docker compose up -d --build
```
+镜像发布在 GHCR:`ghcr.io/bestzwei/libretv`(`latest` / `主.次` / 完整版本号三个 tag,
+`linux/amd64` 与 `linux/arm64` 双架构)。需要固定版本时在 `.env` 中设置
+`LIBRETV_IMAGE=ghcr.io/bestzwei/libretv:2.0.1`。
+
+> 版本号以 `package.json` 为单一来源,部署后可用 `/api/status` 返回的 `version` 字段核对。详见[部署文档](docs/Deployment)。
+
### 手动运行
```bash
@@ -63,6 +74,17 @@ npm test # 核心库单元测试(cms-parser / m3u8
npm run typecheck
```
+## 发布新版本
+
+版本号以 `package.json` 为单一来源,发布镜像由 GitHub Actions 自动完成:
+
+```bash
+npm version patch # 或 minor / major;会更新 package.json 并打 git tag
+git push && git push --tags
+```
+
+CI 校验通过后自动构建并推送 `ghcr.io/bestzwei/libretv:<版本>`(详见[部署文档](docs/Deployment))。
+
## 安全说明
- 密码只保存在服务端环境变量中,前端不持有任何可重放凭证。
diff --git a/docker-compose.yml b/docker-compose.yml
index 206b554..fab64b0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,6 +1,11 @@
services:
libretv:
build: .
+ # 版本管理:镜像 tag 与 package.json 的 version 保持一致
+ # - 使用者:不设置 LIBRETV_IMAGE 即拉取 ghcr.io/bestzwei/libretv:latest(首次部署用 docker compose pull)
+ # - 开发者:docker compose up -d --build 会在本地构建并打上同名 tag
+ # - 需要固定版本时设置 LIBRETV_IMAGE=ghcr.io/bestzwei/libretv:2.0.1
+ image: ${LIBRETV_IMAGE:-ghcr.io/bestzwei/libretv:latest}
container_name: libretv-next
restart: unless-stopped
ports:
diff --git a/docs/Deployment.md b/docs/Deployment.md
index 7fe2d23..2f1a22c 100644
--- a/docs/Deployment.md
+++ b/docs/Deployment.md
@@ -15,6 +15,67 @@ docker compose up -d --build
镜像为多阶段构建(`DOCKER_BUILD=1` 时输出 standalone),运行容器不包含构建工具,体积小。
+## 镜像分发与版本管理
+
+### 版本号:单一事实来源
+
+版本号**只在 `package.json` 的 `version` 字段维护**:
+
+- `/api/status` 返回的 `version` 由 `next.config.ts` 在构建时读取并注入(`process.env.APP_VERSION`);
+- Docker 镜像 tag 建议与它保持一致,使用者可凭 `/api/status` 的返回值核对部署版本。
+
+改版本只需一处:`npm version patch|minor|major`(会同步更新 `package.json` 并打 git tag)。
+
+### 发布镜像(已自动化)
+
+镜像由 GitHub Actions 自动构建并推送到 **GHCR**:`.github/workflows/docker-publish.yml`。
+
+发布流程(开发者侧只需三步):
+
+```bash
+npm version patch # 2.0.0 → 2.0.1,自动更新 package.json 并打 git tag
+git push
+git push --tags
+```
+
+推送到 `v*` tag 后,CI 会先跑类型检查与单测,通过则构建 `linux/amd64` + `linux/arm64`
+双架构镜像并推送,产出三个 tag:
+
+- `ghcr.io/bestzwei/libretv:2.0.1`(完整版本)
+- `ghcr.io/bestzwei/libretv:2.0`(次版本)
+- `ghcr.io/bestzwei/libretv:latest`
+
+无需配置任何 secrets,`GITHUB_TOKEN` 由 GitHub 自动注入并具备 `packages: write` 权限。
+首次发布后,需要到仓库的 **Packages** 页面把镜像可见性设为 Public(默认 Private,拉取需要登录)。
+
+### 使用者侧
+
+```bash
+git clone <本仓库> && cd libretv
+echo "PASSWORD=your-strong-password" > .env
+docker compose pull && docker compose up -d # 拉取 ghcr.io/bestzwei/libretv:latest
+```
+
+锁定特定版本时在 `.env` 中设置:
+
+```bash
+LIBRETV_IMAGE=ghcr.io/bestzwei/libretv:2.0.1
+```
+
+### 本地源码构建(不经过 CI)
+
+`docker-compose.yml` 同时声明了 `build: .` 与 `image:`,本地没有镜像时会用源码构建
+(tag 落在 `ghcr.io/bestzwei/libretv:latest`):
+
+```bash
+docker compose up -d --build
+```
+
+### 构建上下文
+
+仓库含 `.dockerignore`,`node_modules`/`.next`/文档/日志不会进入构建上下文,
+`COPY . .` 不会把本地依赖或构建产物带进镜像,也不会因 `.git` 而使 context 膨胀。
+
### docker-compose.yml
```yaml
@@ -67,8 +128,9 @@ curl -i "http://localhost:8080/api/proxy/http%3A%2F%2F127.0.0.1%3A8080%2F" | hea
## 升级
1. `git pull`
-2. `npm ci && npm run build`(或 `docker compose up -d --build`)
+2. `npm ci && npm run build`(Docker 部署改为 `docker compose pull && docker compose up -d`,源码构建则为 `docker compose up -d --build`)
3. 用户数据(历史/进度/设置)在浏览器端,升级无感迁移。
+4. 可通过 `/api/status` 的 `version` 字段核对线上版本是否已更新。
## 从旧版迁移
@@ -80,7 +142,7 @@ curl -i "http://localhost:8080/api/proxy/http%3A%2F%2F127.0.0.1%3A8080%2F" | hea
```bash
npm install
-PASSWORD=dev-password npm dev # http://localhost:8080
+PASSWORD=dev-password npm run dev # http://localhost:8080
npm run typecheck # TypeScript 检查
npm test # 单元测试(cms-parser / m3u8 / ssrf)
```
diff --git a/next.config.ts b/next.config.ts
index 4c19938..26094de 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -1,10 +1,25 @@
import type { NextConfig } from 'next';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 版本号以 package.json 为单一来源,构建时注入 process.env.APP_VERSION(/api/status 使用) */
+function readAppVersion(): string {
+ try {
+ const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')) as {
+ version?: string;
+ };
+ return pkg.version || '0.0.0';
+ } catch {
+ return '0.0.0';
+ }
+}
const nextConfig: NextConfig = {
// standalone 输出仅供 Docker 镜像构建使用(DOCKER_BUILD=1);
// 本地 next start 在 standalone 模式下不受支持,故按环境切换
output: process.env.DOCKER_BUILD === '1' ? 'standalone' : undefined,
reactStrictMode: true,
+ env: { APP_VERSION: readAppVersion() },
// 采集站/豆瓣等上游地址在运行时由用户配置,构建期无法枚举,关闭图片优化改用 <img>
images: { unoptimized: true },
eslint: { ignoreDuringBuilds: true },
diff --git a/src/app/api/status/route.ts b/src/app/api/status/route.ts
index 183fdec..9f859d0 100644
--- a/src/app/api/status/route.ts
+++ b/src/app/api/status/route.ts
@@ -10,6 +10,7 @@ export async function GET(req: Request) {
return NextResponse.json({
passwordRequired,
verified,
- version: '2.0.0',
+ // 构建时由 next.config.ts 从 package.json 注入
+ version: process.env.APP_VERSION || 'dev',
});
}