diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..a02d402 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,47 @@ +# ============================================================================= +# 构建上下文:只该有源码。下面两类东西一律不进镜像—— +# ① 几百 MB 且跨机不可用的(.venv、node_modules、models、data、media) +# ② 机密与本机状态(.env、scripts/seed、*.db、.local、.trash) +# 第二条比第一条更容易出错:COPY 到的机密会永久留在镜像层里, +# 推去 registry 就等于把加密主密钥发给所有能拉镜像的人,所以 scripts/seed 走 volume 挂载。 +# 注意 frontend/dist 也排除:产物在镜像里由 node 阶段重新构建, +# 带开发机的 dist 进去 = 页面上跑的是上一次构建的代码,且没人看得出来。 +# ============================================================================= +.git +.gitignore +.github +.venv +venv +__pycache__ +**/__pycache__ +*.py[cod] +.pytest_cache +.mypy_cache +.ruff_cache +frontend/node_modules +frontend/dist +node_modules +media +models +data +reports +.local +.trash +docs +backend/tests +nex_animation.db +*.db +*.db-wal +*.db-shm +*.sqlite3 +.env +.env.*.local +scripts/seed +scripts/ui +*.log +nohup.out +*.pid +.idea +.vscode +.DS_Store +._* diff --git a/.env.example b/.env.example index b68c8c8..1c1b5b8 100644 --- a/.env.example +++ b/.env.example @@ -3,6 +3,27 @@ # 变量名 = backend/app/config.py 中 Settings 字段的大写下划线形式 # ============================================================ +# ---------- Docker 部署(docker compose 读这份文件做变量插值并注入容器)---------- +# 只有这一节是「给 compose 看的」,其余都是应用运行时配置(app/config.py 的字段)。 +# 默认形态是一个容器(单端口整站 + SQLite + inline 调度),见 docker-compose.yml 头部。 +# HOST_PORT 对外端口;容器内固定 8000,与 Dockerfile 的 EXPOSE/健康检查对齐 +# AUTO_SEED 容器首启灌 ./scripts/seed 数据包的方式: +# only-missing 只补库里没有的(默认,不动服务器上改过的默认位) +# force 包里说的算 / off 跳过 +# APP_DATABASE_URL / APP_MEDIA_ROOT +# 容器内的库与媒体路径。默认落在挂载点 /app/data 下 —— 别在 .env 里 +# 写宿主机相对路径(./media 之类),那会让库和产物落在容器可写层里, +# 下次 `up --force-recreate` 直接蒸发;宿主路径只在 compose 的挂载那一行改。 +# BASE_IMAGE / NODE_IMAGE / PIP_INDEX_URL / NPM_REGISTRY +# 拉不到 docker.io 或装包慢时覆盖成公司内网/国内镜像源 +# POSTGRES_* / CELERY_CONCURRENCY 只有叠加 docker-compose.scale.yml 时才用到 +# HOST_PORT=8000 +# AUTO_SEED=only-missing +# BASE_IMAGE=python:3.12-slim +# NODE_IMAGE=node:22-alpine +# PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple +# NPM_REGISTRY=https://registry.npmmirror.com + # ---------- 基础设施 ---------- POSTGRES_DB=nexanimation POSTGRES_USER=nex @@ -24,9 +45,10 @@ BOOTSTRAP_PASSWORD=admin1234 # COOKIE_NAME=nex_session # ---------- 前端托管 ---------- -# off = 只出 API,页面由 Vite(dev.sh)或 nginx 容器(docker-compose 的 web)提供 +# off = 只出 API,页面由 Vite(scripts/dev.sh)或单独的 nginx 提供 +# (frontend/Dockerfile + nginx.conf 是「前端另发一份」时的镜像,默认单容器用不到) # on = 后端一并托管 frontend/dist 并做 SPA history 回落,对外只有一个端口 -# (scripts/server.sh 的单机部署形态就是它;缺 dist 时只告警,不会起不来) +# (scripts/server.sh 与 docker-compose.yml 的默认形态都是它;缺 dist 时只告警,不会起不来) SERVE_FRONTEND=off # FRONTEND_DIST_DIR= # 留空 = <仓库根>/frontend/dist diff --git a/.gitignore b/.gitignore index 4f214de..849f42a 100644 --- a/.gitignore +++ b/.gitignore @@ -63,6 +63,10 @@ scripts/seed/ .local/deploy/ *.tar.gz +# ---- 容器数据卷(docker compose 把 ./data 挂进容器当库 + 媒体)---- +# 一旦误提交,别人 pull 下来就自带你这台机器的库和出片产物 +/data/ + # ---- 前端 ---- node_modules/ frontend/dist/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..a352898 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,85 @@ +# ============================================================================= +# Nex Animation Studio · 单容器整站镜像(前端产物 + 后端 + ffmpeg 装在同一个镜像里) +# +# 为什么是一个镜像而不是六个容器:这个项目跑起来只需要 SQLite 和进程内线程池。 +# · TASK_EXECUTOR=inline 时 app/services/daemon.py 的守护线程顶替 celery beat 做周期派发; +# · SERVE_FRONTEND=on 时 app/main.py 直接托管 frontend/dist 并做 SPA history 回落; +# · 于是「nginx 容器 + api + worker + beat + redis」这套拆分在这里没有必然性, +# 剩下的只是一个进程、一个端口、一条数据 volume。升级 = 换镜像,数据在 ./data 不动。 +# 这正是 scripts/server.sh 在裸机上跑的那套形态,只不过搬进了镜像。 +# 真要多机/多 GPU 扩容,再叠加 -f docker-compose.scale.yml 切回 Postgres + Celery。 +# +# 日常部署(配置读同目录 .env,模型配置与主密钥读 ./scripts/seed): +# docker compose up -d --build # 然后打开 http://localhost:8000 +# docker compose logs -f app +# docker compose down # 数据留在 ./data +# 等价的裸命令: +# docker build -t nex-animation:latest . +# docker run -d --name nex-animation -p 8000:8000 \ +# -v $PWD/data:/app/data -v $PWD/scripts/seed:/app/scripts/seed:ro nex-animation:latest +# +# 国内网络:BASE_IMAGE / NODE_IMAGE / PIP_INDEX_URL / NPM_REGISTRY 都能 --build-arg 覆盖, +# 默认值走清华 pip 与 npmmirror(境外构建把后两个换成官方源即可)。 +# ============================================================================= +ARG BASE_IMAGE=python:3.12-slim +ARG NODE_IMAGE=node:22-alpine + +# ---------- 1/2 前端构建 ---------- +FROM ${NODE_IMAGE} AS webbuild +ARG NPM_REGISTRY=https://registry.npmmirror.com +WORKDIR /web +# 先只拷两个清单文件:改一个 .tsx 不该让 npm ci 重跑一遍(这一层能缓存住) +COPY frontend/package.json frontend/package-lock.json ./ +RUN npm config set registry "${NPM_REGISTRY}" \ + && npm ci --cache /tmp/npm-cache --no-audit --no-fund +COPY frontend/ ./ +# build = tsc --noEmit && vite build:类型不过就地构建失败,比在服务器上炸便宜得多 +RUN npm run build + +# ---------- 2/2 运行镜像 ---------- +FROM ${BASE_IMAGE} +ARG PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple +ENV PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 \ + TZ=Asia/Shanghai +WORKDIR /app + +# ffmpeg 是硬依赖:时间线合成、抽帧、时长/码率质检全靠调它(app/services/ffmpeg.py), +# slim 基础镜像里没有,缺了它的表现是「导出成片一路 500」而不是起不来。 +RUN apt-get update \ + && apt-get install -y --no-install-recommends ffmpeg \ + && rm -rf /var/lib/apt/lists/* + +# 依赖单独一层:requirements.txt 里带着 psycopg,将来切 Postgres 扩容不必重建镜像骨架 +COPY backend/requirements.txt ./backend/ +RUN pip install --retries 5 --timeout 60 -i "${PIP_INDEX_URL}" -r backend/requirements.txt + +# 代码布局保持和仓库一致(backend/ + scripts/ + frontend/dist),一个都不挪: +# app/config.py 用 parents[2] 反推仓库根、scripts/seed.py 用同一个办法找 backend/ 和数据集, +# 镜像里改布局就会让「.env 找不到」「数据集看不见」这两类静默失灵重演。 +# PYTHONPATH 指向 backend/ 是为了 uvicorn、celery、seed.py 三种入口都能 import app.*—— +# celery 没有 uvicorn 的 --app-dir 可用,不指它 worker 起不来。 +COPY backend/app ./backend/app +COPY scripts ./scripts +COPY --from=webbuild /web/dist ./frontend/dist + +# 容器内一律用绝对路径:宿主 .env 里那套 ./media、./nex_animation.db 是开发机视角, +# 换个工作目录就漂;库和媒体必须落在挂载点上才扛得住镜像升级。 +ENV DATABASE_URL=sqlite:////app/data/nex_animation.db \ + MEDIA_ROOT=/app/data/media \ + PYTHONPATH=/app/backend \ + SERVE_FRONTEND=on \ + TASK_EXECUTOR=inline \ + AUTO_SEED=only-missing +# 镜像以 root 运行:macOS 的 bind mount 只有 root 写 ./data 最省心。 +# Linux 想换非特权账号:在 compose 里加 user: "1000:1000" 并把 ./data 属主对齐。 +RUN mkdir -p /app/data/media +EXPOSE 8000 +# /health 在 AUTH_ENABLED=true 时也免登录(监控探针和 server.sh verify 都靠它)。 +# slim 里没有 curl,就用自带 python 探,别为一条健康检查装一串包。 +HEALTHCHECK --interval=30s --timeout=5s --start-period=25s --retries=3 \ + CMD python -c "import urllib.request,sys;sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/health',timeout=4).status==200 else 1)" +ENTRYPOINT ["/app/scripts/docker-entrypoint.sh"] +CMD ["uvicorn","app.main:app","--host","0.0.0.0","--port","8000"] diff --git a/README.md b/README.md index b91324d..3cca48a 100644 --- a/README.md +++ b/README.md @@ -293,15 +293,68 @@ cd frontend && npm install && npm run dev # http://localhost:5173 > **SQLite 路径**的父目录由 `app/db.py` 自动创建,`DATABASE_URL='sqlite://////tmp/nex_ui/ui.db'` > 可直接使用(注意 SQLite URL 是 6 个斜杠:3 个协议分隔 + 绝对路径根)。 -### 3.2 生产模式(Postgres + Redis + Celery worker/beat) +### 3.2 打成 Docker(默认**一个容器**:前端和后端同一个端口) ```bash -cp .env.example .env # 修改数据库/Redis 口令 -docker compose up --build # web:8080 api:8000 worker beat db redis +cp .env.example .env # 或直接复用开发机那份:compose 会把 .env 整份注入容器 +docker compose up -d --build # 只起一个容器 nex-animation,对外只有 HOST_PORT(默认 8000) +docker compose logs -f app # 首启会打印「导入部署数据包:seed.py install --only-missing」 +docker compose ps # STATUS 到 healthy 才算起来(探的是 /health) ``` -或本机进程:`celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default -c 2` -与 `celery -A app.worker.celery_app beat`(beat 负责周期派发与断点续跑)。 +镜像里是**后端代码 + 前端构建产物 + ffmpeg**(两段式:node 阶段 `npm ci && npm run build`, +运行阶段 `python:3.12-slim` 装 ffmpeg 与 pip 依赖)。库用 SQLite、任务用 `TASK_EXECUTOR=inline`, +也就是 §3.1 那套单机形态——**没有 nginx 容器、没有 Redis、没有独立 worker/beat**: +后端自己托管 `frontend/dist`(`SERVE_FRONTEND=on` + SPA history 回落),周期派发由进程内的 +`app/services/daemon.py` 守护线程做。换句话说,**docker 形态和 §3.4 的裸机部署只差一层镜像, +跑的是同一份配置**,一个容器就是一个项目。 + +数据全在三处 bind mount 里,换镜像不动数据: + +| 挂载 | 内容 | 为什么这么放 | +| --- | --- | --- | +| `./data` | SQLite 库 + `media/` 出片产物 | 唯一会被写坏的目录,备份它就够了 | +| `./scripts/seed` | 模型配置 + 加密主密钥 + 管理员(只读) | `.dockerignore` 刻意排除它:进镜像 = 把机密烘进层里,谁拉镜像谁拿到主密钥 | +| `./models` | whisper 听写权重(可选) | 465 MB 不该进镜像层 | + +首启由 `scripts/docker-entrypoint.sh` 拿 seed 目录把库灌好,之后交给 `AUTO_SEED` 三种取值: +`only-missing`(默认,只补库里没有的模型,**不动服务器上人工调过的默认位**)、 +`force`(包里说的算)、`off`(跳过)。灌失败只告警不拦启动——页面和 API 本身是好的。 + +常用改动都不用在 Dockerfile 里写死: + +| 想改什么 | 改哪里 | +| --- | --- | +| 对外端口 | `.env` 里 `HOST_PORT=9000`(容器内固定 8000,与 `EXPOSE`/健康检查对齐) | +| 拉不到 docker.io / 装包慢 | `.env` 或 `--build-arg` 覆盖 `BASE_IMAGE`、`NODE_IMAGE`、`PIP_INDEX_URL`、`NPM_REGISTRY` | +| ComfyUI 装在宿主机 | `.env` 里 `COMFYUI_BASE_URL=http://host.docker.internal:9200`(`extra_hosts` 已备 `host-gateway`) | +| 顺带起一个自建 ComfyUI | `docker compose --profile comfy up -d` | + +拉不到 docker.io 时不用改 Dockerfile,把两个基础镜像指到能通的 registry 就行(本机实测可用, +`npm ci`/`apt`/`pip` 三段都走公网镜像源,构建一次约 5 分钟,之后改代码只重跑 COPY 层): + +```bash +BASE_IMAGE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim \ +NODE_IMAGE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine \ +docker compose up -d --build +``` + +**镜像里没有 whisper-cli**:成片台词听写这项质检在容器里会自动跳过(`services/asr.py` 探测不到就 +报告原因,不影响出片)。要它在容器里可用,得自己加一个构建阶段编译 whisper.cpp,或者走 §3.4 裸机形态。 + +**要扩容再叠一层**(多 GPU、多人同时出片、worker 放别的机器): + +```bash +docker compose -f docker-compose.yml -f docker-compose.scale.yml up -d --build +# app + db(postgres) + redis + worker + beat —— 页面仍由 app 一个容器提供 +``` + +compose 的 `environment` 是按键合并、后面的文件赢,所以叠加只是把 `DATABASE_URL` 换成 Postgres、 +`TASK_EXECUTOR` 换成 `celery`,周期派发从 app 内的守护线程交回 beat。本机进程版同命令: +`celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default -c 2` 与 +`celery -A app.worker.celery_app beat`。`frontend/Dockerfile` + `nginx.conf` 留给「前端单独发到 +nginx/CDN」的部署形态,单容器用不到它。 + ### 3.3 冒烟自检 @@ -376,6 +429,13 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \ > 服务器上没有 `whisper-cli` / 听写模型时,只有「台词听写质检」这一项不生效,其余流程照常; > `server.sh status` 会把它标成黄色告警而不是静默降级。`--no-asr` 可以跳过下载(465M 权重)。 +**同一份部署包也能直接跑 Docker**:`deploy.sh` 的必带清单里已经包含 `Dockerfile`、`.dockerignore`、 +`docker-compose.yml`、`docker-compose.scale.yml`、`scripts/docker-entrypoint.sh`,解包后 +`docker compose up -d --build` 就是 §3.2 那个单容器形态。两条路的区别只剩「依赖装在哪」—— +`server.sh install` 装在宿主机上,`docker build` 装在镜像层里;`.env`、`scripts/seed/`、 +数据目录三处的相对位置完全一样,所以先用裸机跑起来、之后想切容器不用搬任何东西 +(反过来也一样:容器用久了想落回裸机,`./data` 里的 SQLite 直接就能被 `server.sh` 读)。 + ## 4. 模型与供应商 ### 4.0 真实模型:ComfyUI · MiniMax H3(已实跑通过) diff --git a/docker-compose.scale.yml b/docker-compose.scale.yml new file mode 100644 index 0000000..7a1bedb --- /dev/null +++ b/docker-compose.scale.yml @@ -0,0 +1,100 @@ +# ============================================================================= +# 扩容层:Postgres + Redis + Celery worker/beat,叠在 docker-compose.yml 之上用 +# +# docker compose -f docker-compose.yml -f docker-compose.scale.yml up -d --build +# (嫌长可以在 .env 里不管它,或者建一个 shell 别名;compose 不会自动读这份文件) +# +# 什么时候才需要它:一台机器跑不过来。多 GPU、多人同时出片、要把 worker 放到 +# 别的机器上——那时候才值得为它多养一个 Postgres、一个 Redis 和两类会「起了但没消费」的进程。 +# 单容器(TASK_EXECUTOR=inline + SQLite)在「单机 + 一两张 ComfyUI 卡」这个量级是够的: +# 出片本身是 ffmpeg 子进程,不受 Python GIL 拖累,INLINE_WORKERS 就是并发闸。 +# +# 机制:compose 的 environment 是**按键合并、后面的文件赢**,所以叠加之后 +# app 容器的 DATABASE_URL / TASK_EXECUTOR 被这里覆盖成 Postgres + celery, +# 页面依然由 app 这一个容器提供(SERVE_FRONTEND=on 没被动过), +# 重活交给 worker,周期派发从 app 内的守护线程交回 beat。 +# 想彻底回到「前后端分离 + nginx」的老形态:frontend/Dockerfile 与 nginx.conf 还在。 +# ============================================================================= +services: + app: + environment: + DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-nex}:${POSTGRES_PASSWORD:-change_this_password}@db:5432/${POSTGRES_DB:-nexanimation} + REDIS_URL: redis://redis:6379/0 + TASK_EXECUTOR: celery + depends_on: + db: { condition: service_healthy } + redis: { condition: service_healthy } + + db: + image: postgres:17 + environment: + POSTGRES_DB: ${POSTGRES_DB:-nexanimation} + POSTGRES_USER: ${POSTGRES_USER:-nex} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change_this_password} + volumes: [postgres_data:/var/lib/postgresql/data] + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-nex} -d ${POSTGRES_DB:-nexanimation}"] + interval: 5s + timeout: 5s + retries: 20 + restart: unless-stopped + + redis: + image: redis:7-alpine + command: ["redis-server", "--appendonly", "yes"] + volumes: [redis_data:/data] + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 3s + retries: 20 + restart: unless-stopped + + worker: + image: nex-animation:latest + # 入口脚本只在第一个参数是 uvicorn 时灌数据集,celery 直接 exec 透传(见 docker-entrypoint.sh) + command: celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default --loglevel=INFO --concurrency=${CELERY_CONCURRENCY:-2} + env_file: + - path: .env + required: false # 任务的真正配置在这里:COMFYUI_BASE_URL、TTS_*、VIDEO_* + environment: + DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-nex}:${POSTGRES_PASSWORD:-change_this_password}@db:5432/${POSTGRES_DB:-nexanimation} + REDIS_URL: redis://redis:6379/0 + MEDIA_ROOT: /app/data/media + TASK_EXECUTOR: celery + TZ: ${TZ:-Asia/Shanghai} + volumes: + # 必须和 app 挂同一个目录:worker 写出的媒体要能被 app 的 /media 路由读到 + - ./data:/app/data + - ./models:/app/models:ro + extra_hosts: + - "host.docker.internal:host-gateway" + depends_on: + db: { condition: service_healthy } + redis: { condition: service_healthy } + restart: unless-stopped + + beat: + image: nex-animation:latest + command: celery -A app.worker.celery_app beat --loglevel=INFO + env_file: + - path: .env + required: false + environment: + DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-nex}:${POSTGRES_PASSWORD:-change_this_password}@db:5432/${POSTGRES_DB:-nexanimation} + REDIS_URL: redis://redis:6379/0 + MEDIA_ROOT: /app/data/media + TASK_EXECUTOR: celery + TZ: ${TZ:-Asia/Shanghai} + volumes: + - ./data:/app/data + extra_hosts: + - "host.docker.internal:host-gateway" + depends_on: + db: { condition: service_healthy } + redis: { condition: service_healthy } + restart: unless-stopped + +volumes: + postgres_data: + redis_data: diff --git a/docker-compose.yml b/docker-compose.yml index 1bc67c2..cabe606 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,77 +1,81 @@ +# ============================================================================= +# Nex Animation Studio · 部署编排(单容器整站:后端 + 前端产物 + SQLite + 进程内调度) +# +# 日常命令: +# docker compose up -d --build 首次部署(构建 + 后台启动) +# docker compose logs -f app 看日志(首启会打印「导入部署数据包」那一行) +# docker compose ps 状态(healthy 才算起来) +# docker compose restart app 改了 .env 之后重启生效 +# docker compose down 停止并删除容器,数据留在 ./data +# 打开 http://localhost:8000 默认账号见 BOOTSTRAP_USERNAME / BOOTSTRAP_PASSWORD +# +# 为什么只有一个服务:库用 SQLite、任务用 TASK_EXECUTOR=inline(进程内线程池 + +# app/services/daemon.py 的派发守护线程),前端产物由后端一并托管, +# 所以不需要 nginx 容器、不需要 Redis、不需要独立 worker/beat。 +# 少三个组件就少三类故障面:没有连不上的 db、没有排队没人消费的 broker、 +# 没有「api 起来了 worker 没起来所以任务永远 pending」。 +# 需要多机 / 多 GPU 扩容时再叠一层(Postgres + Redis + Celery worker + beat): +# docker compose -f docker-compose.yml -f docker-compose.scale.yml up -d --build +# +# 数据分三处 bind mount(都相对本文件,换镜像不动数据): +# ./data SQLite 库 + media 出片产物 ← 唯一会被写坏的目录,值得单独备份 +# ./scripts/seed 模型配置 + 加密主密钥 + 管理员 ← gitignored 的机密,所以不进镜像层 +# ./models whisper 权重等(可选) +# 容器首启由 scripts/docker-entrypoint.sh 拿 seed 目录把库灌好(AUTO_SEED 控制)。 +# +# 配置来源:同目录 .env(compose 会替变量插值读它,并整份注入容器)。 +# 下面 environment 里点名的键是例外——容器里的路径和宿主机不是一回事,必须覆盖。 +# 需要 Docker Compose ≥ v2.24(env_file 的 required: false 写法)。 +# ============================================================================= +name: nex-animation + services: - db: - image: postgres:17 + app: + build: + context: . + args: + # 基础镜像与 pip/npm 源都可以在 .env 里覆盖:直连 docker.io / npmjs 很慢时先探好再构建 + BASE_IMAGE: "${BASE_IMAGE:-python:3.12-slim}" + NODE_IMAGE: "${NODE_IMAGE:-node:22-alpine}" + PIP_INDEX_URL: "${PIP_INDEX_URL:-https://pypi.tuna.tsinghua.edu.cn/simple}" + NPM_REGISTRY: "${NPM_REGISTRY:-https://registry.npmmirror.com}" + image: nex-animation:latest + container_name: nex-animation + restart: unless-stopped + env_file: + - path: .env + required: false # 空机器上先起来再配模型,别让缺 .env 变成起不来 environment: - POSTGRES_DB: ${POSTGRES_DB:-nexanimation} - POSTGRES_USER: ${POSTGRES_USER:-nex} - POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-change_this_password} - volumes: [postgres_data:/var/lib/postgresql/data] - healthcheck: - test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-nex} -d ${POSTGRES_DB:-nexanimation}"] - interval: 5s - timeout: 5s - retries: 20 - restart: unless-stopped - redis: - image: redis:7-alpine - command: ["redis-server", "--appendonly", "yes"] - volumes: [redis_data:/data] - healthcheck: - test: ["CMD", "redis-cli", "ping"] - interval: 5s - timeout: 3s - retries: 20 - restart: unless-stopped - api: - build: ./backend - env_file: .env - environment: - DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-nex}:${POSTGRES_PASSWORD:-change_this_password}@db:5432/${POSTGRES_DB:-nexanimation} - REDIS_URL: redis://redis:6379/0 - MEDIA_ROOT: /app/media - TASK_EXECUTOR: celery - volumes: [media_data:/app/media] - ports: ["8000:8000"] - depends_on: - db: {condition: service_healthy} - redis: {condition: service_healthy} - restart: unless-stopped - worker: - build: ./backend - command: celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default --loglevel=INFO --concurrency=${CELERY_CONCURRENCY:-2} - env_file: .env - environment: - DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-nex}:${POSTGRES_PASSWORD:-change_this_password}@db:5432/${POSTGRES_DB:-nexanimation} - REDIS_URL: redis://redis:6379/0 - MEDIA_ROOT: /app/media - TASK_EXECUTOR: celery - volumes: [media_data:/app/media] - depends_on: - db: {condition: service_healthy} - redis: {condition: service_healthy} - restart: unless-stopped - beat: - build: ./backend - command: celery -A app.worker.celery_app beat --loglevel=INFO - env_file: .env - environment: - DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-nex}:${POSTGRES_PASSWORD:-change_this_password}@db:5432/${POSTGRES_DB:-nexanimation} - REDIS_URL: redis://redis:6379/0 - MEDIA_ROOT: /app/media - TASK_EXECUTOR: celery - volumes: [media_data:/app/media] - depends_on: - db: {condition: service_healthy} - redis: {condition: service_healthy} - restart: unless-stopped - web: - build: ./frontend - ports: ["8080:80"] - depends_on: [api] - restart: unless-stopped - # 自建 ComfyUI(可选):`docker compose --profile comfy up -d` 起一份本地实例。 - # 已有外部 GPU 机器(如 http://10.100.53.199:9200)时不用开这个, - # 只在 .env 里写 COMFYUI_BASE_URL 指过去即可。 + # ---- 容器内路径:宿主 .env 里写的是 ./media、./nex_animation.db,直接透传会漂 ---- + DATABASE_URL: "${APP_DATABASE_URL:-sqlite:////app/data/nex_animation.db}" + MEDIA_ROOT: "${APP_MEDIA_ROOT:-/app/data/media}" + # ---- 整站形态的两把开关:后端托管前端 + 进程内执行后端,都必须在容器里成立 ---- + SERVE_FRONTEND: "on" + TASK_EXECUTOR: "inline" + INLINE_WORKERS: "${INLINE_WORKERS:-2}" + # ---- 账号:库里没用户时首启播种这个管理员,登录后请立刻改口令 ---- + AUTH_ENABLED: "${AUTH_ENABLED:-true}" + BOOTSTRAP_USERNAME: "${BOOTSTRAP_USERNAME:-admin}" + BOOTSTRAP_PASSWORD: "${BOOTSTRAP_PASSWORD:-admin1234}" + AUTO_SEED: "${AUTO_SEED:-only-missing}" + TZ: "${TZ:-Asia/Shanghai}" + # ComfyUI 常跑在宿主机或另一台 GPU 机上;指宿主机就写 http://host.docker.internal:9200 + COMFYUI_BASE_URL: "${COMFYUI_BASE_URL:-}" + ports: + # 对外只有这一个端口;容器内固定 8000(与 EXPOSE / HEALTHCHECK 对齐) + - "${HOST_PORT:-8000}:8000" + volumes: + - ./data:/app/data + - ./scripts/seed:/app/scripts/seed:ro + - ./models:/app/models:ro + extra_hosts: + # Linux 上没有内建的 host.docker.internal,靠 host-gateway 指回宿主机 + # (自建 ComfyUI 装在宿主机时要用)。macOS/Windows 的 Docker Desktop 本来就认这个名字。 + - "host.docker.internal:host-gateway" + + # 自建 ComfyUI(可选):docker compose --profile comfy up -d 起一份容器实例。 + # 已有外部 GPU 机(例如 http://10.100.53.199:9200)时不用开它, + # .env 里把 COMFYUI_BASE_URL 指过去就行;装在宿主机上的话用 http://host.docker.internal:9200。 comfyui: profiles: ["comfy"] image: comfyanonymous/comfyui:latest @@ -87,9 +91,7 @@ services: count: all capabilities: [gpu] restart: unless-stopped + volumes: - postgres_data: - redis_data: - media_data: comfy_models: comfy_input: diff --git a/docs/工程规范.md b/docs/工程规范.md index 55dcf4f..b16ad2e 100644 --- a/docs/工程规范.md +++ b/docs/工程规范.md @@ -75,8 +75,11 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ · | 加一类控件(tooltip / 日期选择 / 命令面板…) | `components/ui/` 新加一个文件包 antd 组件 → `ui/index.ts` 出口 → 需要定尺子就进 `theme/antd.ts` 的 ComponentToken → 登记进 UI规范 §1 的四层分工 | 页面那层永远只见到一个业务组件名;antd 没有合适的(比如整卡热区按钮)才自绘,自绘件登记进 UI规范 §5.2 的「自定义表面族」白名单(探针第 3 道闸逐文件对账) | | 控件档外的高度 | 容器上挂 ``,或给控件传 antd 的 `size` | 控件高度由 antd `componentSize` + token 下发,禁止单个控件写死像素(R9) | -**根目录只允许**:`README.md`、`docker-compose.yml`、`.env`、`.env.example`、`.gitignore` -和上面这些目录。历史上漂在根上的 `.schema shots`、`backend/nex_animation.db`(0 字节空库) +**根目录只允许**:`README.md`、`Dockerfile`、`.dockerignore`、`docker-compose.yml`、 +`docker-compose.scale.yml`、`.env`、`.env.example`、`.gitignore` 和上面这些目录。 +(三个 Docker 文件都在根上,因为单容器镜像要一次 `COPY` 走 `backend/` + `frontend/` + `scripts/` +三处代码——上下文收在任一子目录里都会漏掉另外两个,而漏掉的东西在构建期不报错。) +历史上漂在根上的 `.schema shots`、`backend/nex_animation.db`(0 字节空库) 之类的东西全部来自「在错误的目录里启动服务」,路径锚定修好之后不再产生。 ## 2. `scripts/` 准入规则 @@ -88,6 +91,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ · | `dev.sh` | 开发机上启停前后端(Vite 热更新 + `--reload`) | | `server.sh` | 服务器上安装、构建、启停、看状态、跑验收 | | `deploy.sh` | 开发机上打部署包 / 推到服务器 | +| `docker-entrypoint.sh` | 人不敲它,容器的 `ENTRYPOINT` 敲它:首启把 `./scripts/seed` 数据包灌进库,再把 PID 1 交给 uvicorn(`AUTO_SEED` 控制;celery 入口直接透传,不重复灌) | | `seed.py` | 「部署数据」(模型配置 + 主密钥 + 管理员)的体检与搬运:`doctor` 量数据集与代码是否对得上、`export --fix` 校准并导出、`install` 装前先体检再幂等落地、`boundary` 列数据边界 | | `e2e_selfcheck.py` | 对着真实运行的服务跑一遍 12 节点全流程 | | `evidence_prune.py` | 整理验收台账 `.local/acceptance/evidence.jsonl` | diff --git a/scripts/deploy.sh b/scripts/deploy.sh index 34d7452..7849db7 100755 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -80,7 +80,7 @@ EX=(--exclude '.git/' --exclude '.github/' --exclude '.venv/' --exclude 'venv/' --exclude '.pytest_cache/' --exclude '.mypy_cache/' --exclude '.ruff_cache/' --exclude 'backend/tests/' --include 'frontend/src/components/media/' --exclude 'media/' - --exclude '/models/' --exclude 'frontend/dist/' --exclude '/.local/' + --exclude '/models/' --exclude '/data/' --exclude 'frontend/dist/' --exclude '/.local/' --exclude '/.trash/' --exclude '/reports/' --exclude '/dist/' --exclude '*.db' --exclude '*.db-wal' --exclude '*.db-shm' --exclude '*.sqlite3' --exclude '.env' --exclude '*.log' --exclude 'nohup.out' --exclude '*.pid' @@ -113,10 +113,12 @@ head2 "体检" # 教训就写在这一行的历史里:上一版列了 styles/tokens.css,antd 改版把它拆成 # app.css + index.css,没人记得回来改这条,--check 从此每次都死在「缺少关键文件」。 REQUIRED=(backend/app/main.py backend/app/models/__init__.py backend/requirements.txt - backend/Dockerfile frontend/package.json frontend/tsconfig.json + backend/Dockerfile Dockerfile .dockerignore docker-compose.yml + docker-compose.scale.yml scripts/docker-entrypoint.sh + frontend/package.json frontend/tsconfig.json frontend/index.html frontend/vite.config.ts scripts/server.sh scripts/dev.sh scripts/seed.py scripts/e2e_selfcheck.py - .env.example docker-compose.yml README.md) + .env.example README.md) for f in "${REQUIRED[@]}"; do [ -e "$D/$f" ] || die "部署包缺少关键文件:$f" done @@ -246,7 +248,7 @@ fi ok "后端可启动:import app.main 通过($(cat "$smoke/out") 条路由)" find "$smoke" -mindepth 1 -delete 2>/dev/null; rmdir "$smoke" 2>/dev/null || true -FORBIDDEN=(nex_animation.db backend/tests media models .venv frontend/node_modules reports .local .trash) +FORBIDDEN=(nex_animation.db data backend/tests media models .venv frontend/node_modules reports .local .trash) bad=() for f in "${FORBIDDEN[@]}"; do if [ -e "$D/$f" ]; then bad+=("$f"); fi diff --git a/scripts/docker-entrypoint.sh b/scripts/docker-entrypoint.sh new file mode 100755 index 0000000..ee51a8e --- /dev/null +++ b/scripts/docker-entrypoint.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# ============================================================================= +# 容器入口:先把「部署数据包」灌进库,再把 PID 1 交给 uvicorn / celery。 +# 人不敲它,ENTRYPOINT 敲它(Dockerfile 最后一行)。 +# +# 为什么需要这一步:镜像里只有代码。模型配置、加密主密钥、管理员账号在 +# ./scripts/seed/*.json —— 它被 gitignore 忽略、被 .dockerignore 排除, +# 由 compose 只读挂到 /app/scripts/seed。少了灌数据这一环,新库起来就是个空壳: +# 模型注册表是空的(只有 mock),AUTH_ENABLED=true 下连页面都登不进去。 +# +# 为什么默认 --only-missing:数据集是开发机某一刻的快照,而服务器上人工调过的 +# 默认位是本机事实。每次重启都按包里的值重对齐默认位,等于「重启一次配置回滚一次」。 +# --only-missing 只补库里没有的行、不动已有行 —— 这条语义正是 seed.py 里刚修过的坑。 +# +# 为什么灌失败不拦启动:这时 API 和页面本身是好的,缺的只是几条模型配置; +# 直接 exit 1 会让整站在「数据集比代码旧」这种小事上白屏。告警打到日志, +# `docker compose logs` 看得见,运维自己决定要不要 AUTO_SEED=force 硬灌。 +# +# AUTO_SEED:only-missing 补空缺(默认)| force 包里说的算(覆盖默认位)| off 跳过 +# ============================================================================= +set -uo pipefail + +# 根目录从脚本自己的位置反推,不写死 /app:镜像里的 WORKDIR 是 /app, +# 但把仓库换个目录跑、或在 CI 里离线复现入口契约时路径就不是它了—— +# 写死会让「数据集存在与否」的判断静默变成 False,表现是空库悄悄起来了。 +APP_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +SEED_DIR="$APP_ROOT/scripts/seed" +SEED_PY="$APP_ROOT/scripts/seed.py" + +is_api=0 +[ "${1:-}" = "uvicorn" ] && is_api=1 +# worker/beat 的第一个参数是 celery,同一个库被多个容器同时灌会互相踩,只在 API 进程做一次。 + +mode="${AUTO_SEED:-only-missing}" +if [ "$is_api" = 1 ] && [ "$mode" != "off" ]; then + if [ -s "$SEED_DIR/model_specs.json" ]; then + seed_args=(--only-missing) + [ "$mode" = force ] && seed_args=() + echo "[entrypoint] 导入部署数据包:seed.py install ${seed_args[*]-}(AUTO_SEED=$mode)" + if ! python "$SEED_PY" install ${seed_args[@]+"${seed_args[@]}"}; then + echo "[entrypoint][warn] 数据包没灌进去(每条 error 上面都写了怎么修):服务照常启动," >&2 + echo "[entrypoint][warn] 模型配置可能不完整。补灌:docker compose exec app \\" >&2 + echo "[entrypoint][warn] python scripts/seed.py install --only-missing" >&2 + fi + else + echo "[entrypoint] 没挂 $SEED_DIR 数据集,跳过导入:空库只有 mock 模型可用" + fi +fi + +# exec 而不是直接跑:uvicorn 要当 PID 1,docker stop 的 SIGTERM 才传得进去, +# 30 秒后才会被 SIGKILL 的「超时强杀」也就不会发生(媒体写一半被杀会留脏文件)。 +exec "$@" diff --git a/scripts/seed.py b/scripts/seed.py index b1509fb..e796136 100755 --- a/scripts/seed.py +++ b/scripts/seed.py @@ -383,12 +383,24 @@ def audit_orphan_tables(rep: Report, bind) -> None: "确认后手工 DROP(它不影响部署包,但会让 status 的数据边界说不清)") -def audit_target_db(rep: Report, db) -> None: - """install 的目标库现状:别把部署数据灌进一个正在跑业务的库。""" +def audit_target_db(rep: Report, db, *, only_missing: bool = False) -> None: + """install 的目标库现状:别把部署数据灌进一个正在跑业务的库。 + + 「库里有业务数据」在两档模式下不是一回事,所以报法也不同: + · 覆盖式(不带 --only-missing / 容器 AUTO_SEED=force)真的会用包里的值改掉同名模型, + 指错库就是事故 → 保持黄色告警; + · --only-missing 一行都不动已有数据。而容器每次重启都会走到这里, + 跑了几天的服务器上必然有项目、有事件日志——每次都黄一条, + 等于训练运维无视黄条,所以降级成一行普通提示(只补空缺这件事后面还会再打印一遍)。 + 孤儿表那条与模式无关,照旧告警。 + """ counts = {k: v for k, v in _table_counts(db.bind, BUSINESS_TABLES).items() if v} if counts: - rep.warn("边界", f"目标库里已有业务数据 {counts}:部署数据集只该进干净库," - "确认 DATABASE_URL 没指到开发库(覆盖式导入会改掉这些模型配置)") + if only_missing: + print(f" · 目标库已有业务数据 {counts}:--only-missing 只补库里没有的行,已有配置不动") + else: + rep.warn("边界", f"目标库里已有业务数据 {counts}:部署数据集只该进干净库," + "确认 DATABASE_URL 没指到开发库(覆盖式导入会改掉这些模型配置)") audit_orphan_tables(rep, db.bind) @@ -675,7 +687,7 @@ def do_install(args) -> None: try: if not args.dry_run: target = Report() - audit_target_db(target, db) + audit_target_db(target, db, only_missing=args.only_missing) if target.items: print("体检目标库") target.show() diff --git a/scripts/server.sh b/scripts/server.sh index 06e3817..754a64c 100755 --- a/scripts/server.sh +++ b/scripts/server.sh @@ -22,7 +22,8 @@ # 四个必须写在这里的为什么: # 1) 只起一个 uvicorn 进程,绝不加 --workers。TASK_EXECUTOR=inline 时调度守护线程 # 跑在进程内,多 worker 就是 N 份守护线程同时抢同一批任务、重复派发; -# 要横向扩展请切 TASK_EXECUTOR=celery 并另起 worker(见 docker-compose.yml)。 +# 要横向扩展请切 TASK_EXECUTOR=celery 并另起 worker +# (容器形态见 docker-compose.scale.yml,裸机形态见 README §3.2 末尾的 celery 命令)。 # 2) 前端产物由后端托管(SERVE_FRONTEND=on),所以对外只有一个端口, # 反向代理只需转发一处,/api、/media、/docs 与页面同源,不再有 CORS 与代理漂移。 # 3) 首装顺序是「建表 + 灌数据 → 再启动服务」。先启动也能跑,但应用首启会自己 @@ -154,9 +155,10 @@ seed_data() { "$PYBIN" "$ROOT/scripts/seed.py" boundary || true } -# 单机 .env:不能直接 cp .env.example —— 那份模板是给 docker-compose 用的 -# (Postgres + Redis + TASK_EXECUTOR=celery),照抄到一台裸机上会因为连不上 db -# 而起不来;server.sh 承诺的是「一台机器一条命令跑起来」,所以写 SQLite + inline。 +# 单机 .env:不能直接 cp .env.example —— 那份模板默认给的是 Postgres + Redis + +# TASK_EXECUTOR=celery(只有 docker-compose.scale.yml 那套才有 db/redis),照抄到一台 +# 裸机上会因为连不上 db 而起不来;server.sh 承诺的是「一台机器一条命令跑起来」, +# 所以写 SQLite + inline —— 和 docker-compose.yml 的默认单容器形态是同一份配置。 ensure_env() { [ -f "$ROOT/.env" ] && { ok ".env 就绪"; return 0; } cat > "$ROOT/.env" <<'ENV' @@ -168,7 +170,7 @@ DATABASE_URL=sqlite:///./nex_animation.db MEDIA_ROOT=./media # ---- 执行后端:inline = 进程内线程池,不需要 Redis ---- -# 想横向扩展(多 GPU、多机)再切 celery,并另起 worker/beat,见 docker-compose.yml。 +# 想横向扩展(多 GPU、多机)再切 celery,并另起 worker/beat,见 docker-compose.scale.yml。 TASK_EXECUTOR=inline # ---- 对外 ----