From 1e355e6138e7af4999f0127529fdb5c2a0d08208 Mon Sep 17 00:00:00 2001
From: audio2text dev <dev@audio2text.local>
Date: Sat, 11 Jul 2026 11:37:52 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E7=A6=BB=E7=BA=BF?=
 =?UTF-8?q?=E9=83=A8=E7=BD=B2=E5=AF=BC=E5=85=A5=E9=95=9C=E5=83=8F=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E=20+=20=E6=9B=B4=E6=96=B0=E5=8A=9F=E8=83=BD=E7=89=B9?=
 =?UTF-8?q?=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README:
- 新增「离线部署（导入预构建镜像）」章节：docker load + 启动命令
- 功能特性更新：设置页、任务删除、进度细分、离线运行、/docs 公开

docs/DOCKER.md:
- 新增「导入预构建镜像（离线部署）」完整章节：
  前置要求、导出步骤、需拷贝文件清单、导入启动命令、离线说明、后续更新代码

.gitignore:
- 排除 *.tar（导出的镜像文件不入库）
---
 .gitignore     |  3 ++
 README.md      | 38 ++++++++++++++++++++--
 docs/DOCKER.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 127 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index dc29f78..99a8257 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,6 @@ logs/
 
 # 测试数据与脚本（本地测试用，不入库）
 /test/
+
+# 导出的 Docker 镜像 tar（太大，不入库）
+*.tar
diff --git a/README.md b/README.md
index 471d15f..71f7176 100644
--- a/README.md
+++ b/README.md
@@ -15,11 +15,14 @@
 - **双语字幕**：英文在上、中文在下，亦可单独下载英文 / 中文字幕
 - **faster-whisper 转写**：词级时间戳，断句精确（取首末词时间戳）
 - **NLLB-200 英译中**：ASR 与翻译模型不共驻，翻译时独占显存跑大 batch
-- **任务状态机**：`queued → uploading → extracting → transcribing → segmenting → translating → done`
+- **设置页**：运行时调整 batch_size / beam_size，保存后对后续任务生效（DB 持久化）
+- **任务管理**：删除已完成/失败任务及其产物，进度条按批次细分
+- **任务状态机**：`queued -> uploading -> extracting -> transcribing -> segmenting -> translating -> done`
 - **实时日志页**：按级别分层（debug=详细子步骤 / info=阶段转换 / error=完整 traceback）
 - **定时缓存清理**：任务产物默认保留 7 天，超期连同 DB 记录一并删除
 - **SQLite 持久化**（自包含，无需外部 DB）
-- `/docs`（Swagger UI）受 Basic Auth 保护
+- **离线运行**：模型缓存就位后完全离线，无需访问 HuggingFace
+- `/docs`（Swagger UI）公开访问
 
 ---
 
@@ -115,6 +118,37 @@ AUDIO2TEXT_VARIANT=gpu ./setup.sh
 
 ---
 
+## 离线部署（导入预构建镜像）
+
+已有 `audio2text-gpu.tar` 镜像文件时，新机器无需构建，直接导入即可启动（仍需 NVIDIA 驱动 +
+nvidia container runtime + 模型缓存 `./models`）：
+
+```bash
+# 1. 导入镜像
+docker load -i audio2text-gpu.tar
+
+# 2. 准备配置 + 数据目录
+mkdir -p data-gpu/uploads data-gpu/.work data-gpu/outputs models
+
+# 3. 启动容器（config.gpu.yaml 需自行准备，或从项目仓库取）
+docker run -d --name audio2text-gpu \
+    --gpus all \
+    -p 8001:8000 \
+    -v "$(pwd)/data-gpu:/data" \
+    -v "$(pwd)/models:/models" \
+    -v "$(pwd)/config.gpu.yaml:/app/config.yaml:ro" \
+    --restart unless-stopped \
+    audio2text:gpu
+```
+
+> **模型缓存**：`./models` 目录需包含 Whisper `large-v3-turbo` + NLLB `distilled-1.3B` 权重
+> （约 5.5GB）。首次部署时从源机器拷贝 `models/` 目录，或联网用 `prefetch_models.sh` 预拉。
+> 镜像内置 `HF_HUB_OFFLINE=1`，模型就位后完全离线运行，无需访问 HuggingFace。
+
+详细步骤见 [Docker 说明 - 导入预构建镜像](./docs/DOCKER.md#导入预构建镜像离线部署)。
+
+---
+
 ## 入口
 
 | 入口 | 地址 |
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 7e586b6..a34673d 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -94,6 +94,94 @@ docker compose --profile cpu up -d --build   # CPU 生产
 docker compose --profile gpu up -d --build   # GPU 生产（需 nvidia runtime）
 ```
 
+### 导入预构建镜像（离线部署）
+
+当目标机器无法访问 Docker Hub（或构建太慢）时，可在已构建好镜像的机器上导出 tar，
+拷到新机器导入，跳过整个构建过程。
+
+#### 前置要求（新机器）
+
+- **NVIDIA GPU 驱动**（宿主机）
+- **nvidia container runtime**（`nvidia-container-toolkit`）
+- Docker
+- `config.gpu.yaml` 配置文件（从项目仓库取，或自行编写）
+- 模型缓存 `./models` 目录（约 5.5GB，从源机器拷贝或联网预拉）
+
+验证 GPU 可用：
+
+```bash
+nvidia-smi   # 宿主能看到 GPU
+docker run --rm --gpus all nvidia/cuda:12.1.0-runtime-ubuntu22.04 nvidia-smi
+```
+
+#### 步骤 1：源机器导出镜像
+
+```bash
+# 在已构建好 audio2text:gpu 镜像的机器上
+docker save -o audio2text-gpu.tar audio2text:gpu
+ls -lh audio2text-gpu.tar   # ~4.3GB
+```
+
+#### 步骤 2：拷贝到新机器
+
+需要拷贝的文件：
+
+| 文件/目录 | 大小 | 说明 |
+|---|---|---|
+| `audio2text-gpu.tar` | ~4.3GB | Docker 镜像（含 ffmpeg + torch + faster-whisper + transformers + app 代码） |
+| `config.gpu.yaml` | <1KB | GPU 配置文件 |
+| `models/` | ~5.5GB | 模型缓存（Whisper large-v3-turbo + NLLB distilled-1.3B 权重） |
+
+> `models/` 可不拷贝，新机器联网时用 `prefetch_models.sh` 预拉。但离线部署必须拷贝。
+
+```bash
+# 用 scp / rsync / U盘 等方式拷贝
+scp audio2text-gpu.tar config.gpu.yaml user@newhost:~/audio2text/
+rsync -avP models/ user@newhost:~/audio2text/models/
+```
+
+#### 步骤 3：新机器导入并启动
+
+```bash
+cd ~/audio2text
+
+# 1. 导入镜像
+docker load -i audio2text-gpu.tar
+# 输出：Loaded image: audio2text:gpu
+
+# 2. 准备数据目录
+mkdir -p data-gpu/uploads data-gpu/.work data-gpu/outputs
+
+# 3. 启动容器
+docker run -d --name audio2text-gpu \
+    --gpus all \
+    -p 8001:8000 \
+    -v "$(pwd)/data-gpu:/data" \
+    -v "$(pwd)/models:/models" \
+    -v "$(pwd)/config.gpu.yaml:/app/config.yaml:ro" \
+    --restart unless-stopped \
+    audio2text:gpu
+
+# 4. 验证
+curl -s http://127.0.0.1:8001/health | python -m json.tool
+# 应见 cuda_available=true, gpu="NVIDIA GeForce RTX 3090"
+```
+
+打开 `http://127.0.0.1:8001/` 即可使用。
+
+#### 离线运行说明
+
+镜像内置 `HF_HUB_OFFLINE=1` + `TRANSFORMERS_OFFLINE=1` 环境变量，模型缓存就位后
+**完全离线运行**，不会尝试访问 HuggingFace。这避免了离线环境下 transformers
+pipeline 因网络请求超时导致的翻译失败。
+
+#### 后续更新代码
+
+导入的镜像包含导出时的 app 代码。如需更新代码，有两个选择：
+
+1. **重新构建**：把项目代码拷到新机器，`docker build --build-arg VARIANT=gpu -t audio2text:gpu .`
+2. **挂载源码**（临时调试）：启动时加 `-v "$(pwd)/app:/app/app"` 覆盖镜像内代码
+
 ---
 
 ## 缓存分层与删除边界