autoclip/DOCKER.md

Docker 部署与排错

English · 返回首页 · 常见问题

适合 Linux、Intel Mac、服务器或希望使用 Web 界面的用户。需要 Docker 和 Docker Compose v2；命令使用 docker compose。视频、模型、缓存和导出文件会占用额外磁盘，按素材规模预留空间。

首次启动

git clone https://github.com/zhouxiaoka/autoclip.git
cd autoclip
cp env.example .env

编辑 .env，设置 LLM_PROVIDER、API_MODEL_NAME 和对应的 API Key，也可以启动后在 Web 设置页配置。例：

LLM_PROVIDER=dashscope
API_MODEL_NAME=qwen-plus
API_DASHSCOPE_API_KEY=your_api_key

模型是否可用取决于服务商与账号权限。设置页已保存的模型配置可能优先于环境变量；更换提供商后应测试连接并保存。

mkdir -p data logs uploads
docker compose build
docker compose run --rm --no-deps --user root --entrypoint sh autoclip -c 'chown -R autoclip:autoclip /app/data /app/logs /app/uploads'
docker compose up -d
docker compose ps

目录归属命令让镜像中的 autoclip 用户能够写入三个项目绑定目录，尤其适用于 Linux。它会修改这些目录及其内容的文件归属；新部署可先在空目录中完成。无需将权限设为 777。

入口	默认地址
Web 界面	http://localhost:3000
API 文档	http://localhost:8000/docs
健康检查	http://localhost:8000/api/v1/health/
Flower 任务监控	http://localhost:5555

默认编排同时启动主应用、Redis、Celery Worker、Celery Beat 和 Flower。它面向本地或可信网络使用；若部署到公网，需要另行设置访问控制与网络隔离，尤其不要直接开放 Redis 和 Flower。

模型与字幕

支持的提供商与环境变量以 env.example 和 docker-compose.yml 为准。Web 设置页可以保存模型配置，不需要仅靠环境变量。

本地模型需要在宿主机启动。Docker Desktop 访问宿主机 Ollama 的示例：

LLM_PROVIDER=ollama
OPENAI_BASE_URL=http://host.docker.internal:11434/v1
API_MODEL_NAME=qwen2.5:7b

Linux Docker Engine 可能需要在 autoclip 和 celery-worker 两个服务下加入：

extra_hosts:
  - "host.docker.internal:host-gateway"

该主机名能解析并不保证模型可连接：宿主机模型服务还需要监听容器可访问的接口，防火墙允许相应连接。容器中的 localhost 不能访问宿主机的模型服务。环境变量或编排变更后运行 docker compose up -d 重建受影响容器；若设置页保存过旧地址，也要同步修改。

没有字幕的视频需要准备本地转写组件与模型。首次安装较耗时，建议先使用本地视频加 SRT 验证主流程，详见 安装指南。

排错

docker compose ps
docker compose logs --tail=100 autoclip celery-worker
curl -f http://localhost:8000/api/v1/health/

现象	检查项
页面打不开	autoclip 是否运行，3000 / 8000 端口是否被其他进程占用
项目一直排队	celery-worker 与 Redis 是否健康，是否保留了编排中的专用队列参数
Permission denied / 数据库只读	data/、logs/、uploads/ 是否对容器用户可写
模型测试失败	提供商、模型名、API Key 和保存的 Base URL；本地模型是否能从容器访问
没有生成片段	按字幕、分析、评分、导出阶段排查，见 FAQ

修改宿主机端口时，只修改映射左侧，例如 "3001:3000"，再使用新的宿主机端口访问。不要删除数据库来解决启动问题。

数据与备份

默认 Compose 使用绑定目录，而不是名为 autoclip_data 的视频数据卷：

宿主机	容器	内容
./data	/app/data	数据库、项目、配置等
./logs	/app/logs	日志
./uploads	/app/uploads	上传文件

redis_data 是 Redis 的命名卷，不能代替项目文件备份。备份前等待任务结束并停止服务，再复制三个目录和 .env：

docker compose stop
tar -czf "../autoclip-backup-$(date +%Y%m%d-%H%M%S).tar.gz" data logs uploads .env
docker compose start

备份含本地视频和可能含密钥的配置，请保存在受控位置。恢复前停止服务、保留当前目录副本，然后恢复数据并核对文件归属；不要直接覆盖唯一一份数据。

兼容脚本

根目录脚本仍可用，实际逻辑统一在 scripts/runtime/docker.sh：

./docker-start.sh               # 生产编排，构建后启动
./docker-start.sh dev           # 开发编排
./docker-status.sh dev          # 检查同一开发项目的全部服务
./docker-stop.sh dev            # 停止开发容器，保留数据
./docker-stop.sh dev --cleanup  # 移除开发容器与网络，仍保留绑定数据与命名卷

--no-build 可用于已有镜像的启动。状态检查在缺失、退出或尚未健康时返回非零值。旧的 --force 全局清理入口已移除；脚本不会清理其他项目的容器、镜像或卷。启动成功只表示容器已创建，服务健康应再用状态命令确认。

更新与停止

备份后更新源码并重建。存在本地改动时先检查 git status 并处理改动，不要强制覆盖。

git pull --ff-only
docker compose up -d --build

暂时停止使用 docker compose stop；删除容器但保留绑定数据使用 docker compose down。不要为了日常重启加 --volumes。

开发模式

开发编排 用于源码开发；它与生产编排可能使用相同端口，不要同时启动：

docker compose -f docker-compose.dev.yml up -d --build
docker compose -f docker-compose.dev.yml logs -f

更多排错见 FAQ，版本变更见 Releases。