video_ms Docker 部署说明

本文以仓库中的实际编排文件为准，说明如何使用以下文件部署 video_ms。

如果客户现场没有现成的 MySQL 和 Redis，可以直接使用 docker-compose.local.yml 自建这两个基础组件；它不仅适合本地联调，也可以作为“先把依赖服务跑起来”的参考编排。

当前仓库中的 compose 文件用途如下：

• docker-compose.yml：单机主节点，启动 api、worker、beat，依赖外部 MySQL 和 Redis。
• docker-compose.worker.yml：工作节点，启动 api、worker，依赖外部 MySQL 和 Redis。
• docker-compose.local.yml：本地联调，启动 mysql、redis、api、worker、beat。
• docker-compose.local-weaknet.yml：弱网/故障注入测试场景。

镜像统一使用项目根目录的 Dockerfile 构建，服务启动脚本分别为：

• deploy/start-api.sh
• deploy/start-worker.sh
• deploy/start-beat.sh

---

1. 服务说明

服务	实际启动命令	说明
api	deploy/start-api.sh	启动前先执行 alembic upgrade head，然后以 uvicorn 监听 0.0.0.0:8000。
worker	deploy/start-worker.sh	启动 Celery Worker，消费 render,default 两个队列。
beat	deploy/start-beat.sh	启动 Celery Beat。整个集群只应保留 1 个实例。
mysql	仅 docker-compose.local.yml	本地测试数据库，端口映射为 13306:3306。
redis	仅 docker-compose.local.yml	本地测试 Redis，端口映射为 16379:6379。

---

2. 前置条件

• 已安装 Docker 和 Docker Compose V2。
• 项目根目录下存在可用的 .env 文件；若没有，可先执行 cp .env.example .env。
• 若使用 docker-compose.yml 或 docker-compose.worker.yml，需要提前准备好可访问的 MySQL 和 Redis。
• 若客户环境没有现成的 MySQL 和 Redis，可优先使用 docker-compose.local.yml 自建。
• MySQL 数据库名需与 VIDEO_MS_DATABASE_NAME 一致。

---

3. 环境变量

.env.example 中已经给出了主要变量。实际部署时重点关注：

• VIDEO_MS_DATABASE_HOST
• VIDEO_MS_DATABASE_PORT
• VIDEO_MS_DATABASE_NAME
• VIDEO_MS_DATABASE_USERNAME
• VIDEO_MS_DATABASE_PASSWORD
• VIDEO_MS_REDIS_HOST
• VIDEO_MS_REDIS_PORT
• VIDEO_MS_REDIS_PASSWORD
• REDIS_PASSWORD
• WORKER_SHM_SIZE
• CELERY_CONCURRENCY
• API_WORKERS

说明：

• api 启动时会执行数据库迁移，因此 VIDEO_MS_DATABASE_* 必须可用。
• docker-compose.yml 会把 VIDEO_MS_REDIS_HOST 强制覆盖成 127.0.0.1，并把 VIDEO_MS_REDIS_PASSWORD 强制覆盖成 ${REDIS_PASSWORD:-video_ms_redis}。
• docker-compose.worker.yml 不会覆盖数据库和 Redis 地址，直接读取 .env。
• docker-compose.local.yml 直接在 compose 文件内写死了本地联调所需的大部分数据库和 Redis 参数。

---

4. 构建镜像

在项目根目录执行：

docker compose build

如果只想按某个编排文件显式构建，也可以执行：

docker compose -f docker-compose.local.yml build
docker compose -f docker-compose.worker.yml build

api 服务包含 build: .，首次构建会安装 Poetry 依赖以及渲染相关运行库，耗时会较长。

---

5. 单机主节点部署：docker-compose.yml

5.1 适用场景

用于单机部署主节点，启动以下服务：

• api
• worker
• beat

这份文件当前 没有定义 redis 服务，也没有定义 mysql 服务，因此需要你提前准备：

• 外部 MySQL
• 本机可访问的 Redis

如果客户环境暂时没有这两类基础组件，建议直接改用 7. 本地联调：docker-compose.local.yml 的方式先自建 MySQL 和 Redis，再进行业务服务部署。

同时，api、worker、beat 都声明了：

• network_mode: host
• env_file: .env

其中 api 与 worker 还挂载了：

• ./logs:/app/video_ms/logs
• ./data:/app/video_ms/data

beat 目前未挂载卷。

5.2 配置要求

部署前至少确认：

• .env 中的 VIDEO_MS_DATABASE_* 指向可访问的 MySQL。
• 本机 127.0.0.1:6379 上有可用 Redis，且密码与 REDIS_PASSWORD 一致。

原因是该文件内显式设置了：

• VIDEO_MS_REDIS_HOST=127.0.0.1
• VIDEO_MS_REDIS_PASSWORD=${REDIS_PASSWORD:-video_ms_redis}

5.3 启动命令

cp .env.example .env
docker compose up -d

5.4 运行特征

• api 健康检查地址：http://localhost:8000/health
• worker 默认共享内存：${WORKER_SHM_SIZE:-2gb}
• worker 默认并发：${CELERY_CONCURRENCY:-1}
• api 对外监听宿主机 8000

5.5 验证命令

docker compose ps
curl -sf http://127.0.0.1:8000/health

---

6. 工作节点部署：docker-compose.worker.yml

6.1 适用场景

用于扩展工作节点，启动：

• api
• worker

不启动：

• beat
• redis
• mysql

这份文件也使用 network_mode: host，并通过 .env 读取数据库和 Redis 配置。

6.2 配置要求

部署前需要在 .env 中配置：

• VIDEO_MS_DATABASE_HOST
• VIDEO_MS_DATABASE_PORT
• VIDEO_MS_DATABASE_NAME
• VIDEO_MS_DATABASE_USERNAME
• VIDEO_MS_DATABASE_PASSWORD
• VIDEO_MS_REDIS_HOST
• VIDEO_MS_REDIS_PORT
• VIDEO_MS_REDIS_PASSWORD

另外可按需配置：

• WORKER_SHM_SIZE，默认 ${WORKER_SHM_SIZE:-4gb}
• CELERY_CONCURRENCY，默认 ${CELERY_CONCURRENCY:-2}

6.3 启动命令

cp .env.example .env
docker compose -f docker-compose.worker.yml up -d

6.4 验证命令

docker compose -f docker-compose.worker.yml ps
curl -sf http://127.0.0.1:8000/health

说明：

• 工作节点上的 api 同样会在启动时执行数据库迁移。
• 集群中不要在工作节点额外启动 beat。

---

7. 本地联调：docker-compose.local.yml

这份文件适合本地测试，也适合客户环境中 没有现成 MySQL / Redis 时先自建基础服务 的场景，包含：

• mysql
• redis
• api
• worker
• beat

实际端口与默认参数如下：

• MySQL：13306:3306
• Redis：16379:6379
• API：8000:8000
• worker 默认 shm_size=${WORKER_SHM_SIZE:-4gb}
• worker 默认 CELERY_CONCURRENCY=${CELERY_CONCURRENCY:-2}
• worker 默认 RENDER_THREADS=${RENDER_THREADS:-4}
• api 默认 API_WORKERS=1

容器内固定使用：

• VIDEO_MS_DATABASE_HOST=mysql
• VIDEO_MS_DATABASE_PORT=3306
• VIDEO_MS_DATABASE_NAME=video_ms
• VIDEO_MS_DATABASE_USERNAME=root
• VIDEO_MS_DATABASE_PASSWORD=root123
• VIDEO_MS_REDIS_HOST=redis
• VIDEO_MS_REDIS_PORT=6379
• VIDEO_MS_REDIS_PASSWORD=redis123

启动命令：

docker compose -f docker-compose.local.yml up -d

如果客户机器上希望直接用这一套完成部署，文档重点如下：

• 该文件会一并启动 MySQL 和 Redis，不依赖外部数据库或缓存。
• 业务服务也会同时启动，即 api、worker、beat 会和 mysql、redis 一起拉起。
• 对外访问端口分别是 8000、13306、16379。
• 若后续要切换到客户自建或云上的 MySQL / Redis，再把部署方式切回 docker-compose.yml 或 docker-compose.worker.yml。

---

8. 弱网测试：docker-compose.local-weaknet.yml

该文件用于本地弱网或故障注入测试。使用前请先阅读文件内定义以及相关 deploy 脚本，再按需启动。

---

9. 数据库迁移

api 服务启动时会自动执行：

alembic upgrade head

如果需要手动执行，可进入实际使用的 api 容器运行，例如：

docker compose exec api bash -c "cd /app && alembic upgrade head"
docker compose -f docker-compose.worker.yml exec api bash -c "cd /app && alembic upgrade head"
docker compose -f docker-compose.local.yml exec api bash -c "cd /app && alembic upgrade head"

---

10. 常用运维命令

主节点：

docker compose ps
docker compose logs -f api
docker compose logs -f worker
docker compose logs -f beat
docker compose restart worker
docker compose down

工作节点：

docker compose -f docker-compose.worker.yml ps
docker compose -f docker-compose.worker.yml logs -f api
docker compose -f docker-compose.worker.yml logs -f worker
docker compose -f docker-compose.worker.yml restart worker
docker compose -f docker-compose.worker.yml down

本地联调：

docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs -f api
docker compose -f docker-compose.local.yml logs -f worker
docker compose -f docker-compose.local.yml logs -f beat
docker compose -f docker-compose.local.yml down

---

11. 故障排查

现象	可能原因
api 启动失败	MySQL 不可达、数据库迁移失败、宿主机 8000 端口被占用。
worker 不消费任务	Redis 配置错误、CELERY_CONCURRENCY 配置异常、Worker 未成功启动。
渲染进程异常退出	WORKER_SHM_SIZE 太小，或机器内存不足。
定时任务重复执行	集群里启动了多个 beat。
主节点 compose 启动时报 depends_on.redis 相关错误	docker-compose.yml 当前引用了 redis 依赖，但文件里未定义 redis 服务；部署前需要自行确认编排方式与外部 Redis 接入策略。

---

12. 文件对照表

文件	实际用途
docker-compose.yml	主节点，启动 api、worker、beat，依赖外部 MySQL 和本机 Redis。
docker-compose.worker.yml	工作节点，启动 api、worker，依赖外部 MySQL 和 Redis。
docker-compose.local.yml	本地联调，启动完整的 MySQL、Redis、API、Worker、Beat。
docker-compose.local-weaknet.yml	弱网与故障注入测试。
deploy/start-api.sh	执行迁移后启动 uvicorn。
deploy/start-worker.sh	启动 Celery Worker。
deploy/start-beat.sh	启动 Celery Beat。