From 24978e98431fdf097a6bfdb64b98c5f109964a74 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Thu, 5 Nov 2026 18:52:38 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8A=8A=E3=80=8C=E6=9C=8D=E5=8A=A1=E5=99=A8?= =?UTF-8?q?=E4=B8=8A=E9=82=A3=E4=BB=BD=20.env=20=E5=88=B0=E5=BA=95?= =?UTF-8?q?=E7=AE=A1=E4=BB=80=E4=B9=88=E3=80=8D=E5=86=99=E6=AD=BB=EF=BC=9A?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF=E9=BB=98=E8=AE=A4=E6=94=B9=E6=88=90=E5=8D=95?= =?UTF-8?q?=E5=AE=B9=E5=99=A8=E7=9C=9F=E7=9B=B8=EF=BC=8Ccompose=20?= =?UTF-8?q?=E8=A6=86=E7=9B=96=E7=9A=84=E9=94=AE=E9=80=90=E6=9D=A1=E7=82=B9?= =?UTF-8?q?=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 部署前必问的三个问题,答案以前都藏在别的文件里,这次直接写进 .env.example 与 README §3.2。 一、.env 不是「开发用的那份」,是「每台机器一份的那份」 它 gitignored、不在部署包里(deploy.sh 的「不随包走」清单里就有它),仓库根这份是开发机的 (SQLite、Vite 端口、本机口令),服务器上那份由 cp .env.example .env 生成,两份互不影响。 之前 .env.example 头部没交代这件事,于是「根目录 .env 是配置开发的?那服务器上改哪」这个问题 只能靠人脑补答案。补上四行说明。 二、对外端口配在哪:服务器那份 .env 的 PORT 一行,不在 compose 里 compose 只是引用它(ports: "${PORT:-${HOST_PORT:-8000}}:8000"),读 .env 读两遍: 先替 ${PORT} 插值得到端口映射,再整份注入容器当环境变量。 顺手填掉一个真坑:compose 的 environment 覆盖 DATABASE_URL / MEDIA_ROOT / SERVE_FRONTEND / TASK_EXECUTOR / 容器内 PORT 这五个键,运维在 .env 里改前四个是**完全没反应**的—— 这正是本仓最忌讳的「写了不生效」,而 .env.example 作为模板恰恰把它们写成生效态。 现在逐个点名:前四个标注「Docker 形态被 APP_* 覆盖」,容器内落点改 APP_DATABASE_URL / APP_MEDIA_ROOT 那两行。 三、.env.example 的默认值改成单容器形态(原来那套会让人以为在用 Postgres) 模板里原先是 DATABASE_URL=postgresql+…@db:5432、TASK_EXECUTOR=celery、SERVE_FRONTEND=off、 POSTGRES_*/REDIS_URL 全生效,而 §3.2 又让你 cp 它去部署 Docker——照做之后文件说「Postgres + Celery + 不托管前端」,实际跑的是「SQLite + inline + 托管前端」,读文件的人被指错方向。 现在默认 SQLite / inline / on(与 compose 强制的那套一致),Postgres/Redis/Celery 七个键 整段注释掉并注明「只在 -f docker-compose.scale.yml 时生效」。生效键从 45 降到 40: 留下的每一个都有读取方。 连带修掉 README §3.4 那句「模板里那套是 Postgres + Celery,cp 会起不来」——现在 cp 也能起来, 两条路径等价,这个矛盾说法本身就成了误导。 四、compose 里的 comfyui 服务:默认不参与,README 说明白 它带 profiles: ["comfy"],docker compose config --services 只有 app,不 --profile comfy 就 不会起,GPU 预留也不生效。算力在远端(模型中心里那三条 base_url)时它就是死代码, 只是给「算力恰好装在本机、想用容器跑一份 ComfyUI」留的开关。§3.2 与常用改动表各补一句。 验证:docker compose config --services 仍只有 app,published 仍随 PORT 变化, 容器内 DATABASE_URL/MEDIA_ROOT/SERVE_FRONTEND/TASK_EXECUTOR 仍是挂载点内那套; deploy.sh --check 全绿(215 文件/7.5M,数据包 8 条模型配置体检通过); 两份 env 0 未知键 0 模型键;backend 全量 502 passed / 1 skipped。 --- .env.example | 45 +++++++++++++++++++++++++-------------------- README.md | 20 +++++++++++++++++--- docker-compose.yml | 3 ++- 3 files changed, 44 insertions(+), 24 deletions(-) diff --git a/.env.example b/.env.example index b1bccb8..8ced0fb 100644 --- a/.env.example +++ b/.env.example @@ -1,5 +1,7 @@ # ============================================================ # Nex Animation Studio · 运行时配置(复制为 .env 后按需修改) +# · .env 是「每台机器一份」的配置:它不进仓库,服务器上的那份由你从本文件复制, +# 跟开发机那份互不影响。部署包也不带它——先 cp 再改,是唯一需要编辑的文件。 # · 应用配置项 = backend/app/config.py 里 Settings 字段的大写下划线形式(多余键忽略) # · 端口优先级:命令行参数 > 环境变量 > 本文件的 PORT # · 模型配置不在这里:地址、模型名、步数、超时、并发与限流、单价、默认位都在数据库, @@ -16,10 +18,13 @@ FRONTEND_PORT=5173 # ---------- Docker 构建与首启(compose 读,应用不读)---------- # AUTO_SEED:首启导入 scripts/seed 数据包的方式 only-missing(默认)| force | off # APP_DATABASE_URL / APP_MEDIA_ROOT:容器内的库与产物路径,必须落在挂载点里 -# (./data ↔ /app/data,./media ↔ /app/media) +# (./data ↔ /app/data,./media ↔ /app/media);想改容器里的落点改这两行, +# 改下面的 DATABASE_URL / MEDIA_ROOT 没用——它们会被 compose 覆盖掉。 # AUTO_SEED=only-missing # APP_DATABASE_URL=sqlite:////app/data/nex_animation.db # APP_MEDIA_ROOT=/app/media +# 下面这几项 compose 也替你钉死了,单容器形态不用碰:SERVE_FRONTEND=on、TASK_EXECUTOR=inline、 +# 以及容器内的 PORT=8000(本文件的 PORT 只决定对外映射到哪个端口)。 # APT_MIRROR=mirrors.tuna.tsinghua.edu.cn # apt 源(ffmpeg 在这一层装),默认官方 deb.debian.org # BASE_IMAGE=python:3.12-slim # NODE_IMAGE=node:22-alpine @@ -27,15 +32,11 @@ FRONTEND_PORT=5173 # NPM_REGISTRY=https://registry.npmmirror.com # POSTGRES_* / CELERY_CONCURRENCY 只在叠加 docker-compose.scale.yml 时用到 -# ---------- 基础设施 ---------- -POSTGRES_DB=nexanimation -POSTGRES_USER=nex -POSTGRES_PASSWORD=change_this_password -DATABASE_URL=postgresql+psycopg://nex:change_this_password@db:5432/nexanimation -REDIS_URL=redis://redis:6379/0 -# 产物根目录:图片/视频/配音/上传素材/缩略图,由后端 /media/* 直出。 -# 相对路径锚定仓库根;Docker 形态下必须是挂载点内的绝对路径,否则产物落在容器可写层, -# 下次重建镜像就没了。 +# ---------- 存储 ---------- +# 这两行是「不带 compose 裸跑」时的取值(相对路径锚定仓库根); +# Docker 形态下 compose 把它们覆盖成 APP_DATABASE_URL / APP_MEDIA_ROOT 那两个挂载点。 +# 产物落在容器可写层的后果是下次重建镜像就没了,所以容器里必须是挂载点内的绝对路径。 +DATABASE_URL=sqlite:///./nex_animation.db MEDIA_ROOT=./media MEDIA_URL_PREFIX=/media CORS_ORIGINS=* @@ -48,20 +49,24 @@ BOOTSTRAP_USERNAME=admin BOOTSTRAP_PASSWORD=admin1234 # COOKIE_NAME=nex_session -# ---------- 前端托管 ---------- -# off = 只出 API,页面由 Vite(scripts/dev.sh)或单独的 nginx 提供 -# on = 后端一并托管 frontend/dist 并做 SPA history 回落,对外只有一个端口 -SERVE_FRONTEND=off +# ---------- 前端托管 + 任务执行后端(默认 = 单容器那一套)---------- +# on = 后端一并托管 frontend/dist 并做 SPA history 回落,对外只有一个端口 +# inline = 进程内线程池 + 内置派发守护,不需要 Redis +SERVE_FRONTEND=on # FRONTEND_DIST_DIR= # 留空 = <仓库根>/frontend/dist +TASK_EXECUTOR=inline +INLINE_WORKERS=2 -# ---------- 任务执行后端 ---------- -# celery = 生产模式(Redis broker + worker + beat) -# inline = 单机模式(进程内线程池 + 内置派发守护,无需 Redis) -TASK_EXECUTOR=celery +# ---------- 扩容层专用:只在 -f docker-compose.scale.yml 时生效 ---------- +# 叠加之后 scale.yml 会用 Postgres + celery 覆盖上面的 DATABASE_URL / TASK_EXECUTOR, +# 独立 worker 与 beat 各起一个容器;不叠加时这些键没人读,所以默认全部注释掉。 +# POSTGRES_DB=nexanimation +# POSTGRES_USER=nex +# POSTGRES_PASSWORD=change_this_password +# REDIS_URL=redis://redis:6379/0 # CELERY_BROKER_URL=redis://redis:6379/0 # CELERY_RESULT_BACKEND=redis://redis:6379/1 -INLINE_WORKERS=2 -CELERY_CONCURRENCY=2 +# CELERY_CONCURRENCY=2 # ---------- 调度节奏 / 重试 / 断点续跑 ---------- DISPATCH_INTERVAL_SECONDS=5 diff --git a/README.md b/README.md index 611ff0e..d5d7279 100644 --- a/README.md +++ b/README.md @@ -303,6 +303,19 @@ docker compose logs -f app # 首启会打印「导入部署数据包:seed.p docker compose ps # STATUS 到 healthy 才算起来(探的是 /health) ``` +**`.env` 是「每台机器一份」的文件**:仓库根那份是你开发机的配置(SQLite、Vite 端口、本机口令), +它 gitignored、不在部署包里;服务器上是 `cp .env.example .env` 生成的另一份,**对外的端口就配在 +服务器那份 `.env` 的 `PORT=` 一行**,不在 compose 文件里(compose 只是引用它)。compose 读 `.env` +读两遍:先替 `${PORT}` 插值得到 `ports` 映射,再把整份注入容器当环境变量。有两个例外要记住: +容器内监听的 `PORT` 被 compose 钉成 8000(改 `.env` 只改对外映射),而 `DATABASE_URL`、 +`MEDIA_ROOT`、`SERVE_FRONTEND`、`TASK_EXECUTOR` 这四行在 `.env` 里改了没用——compose 的 +`environment` 覆盖它们,要挪容器内的落点请改 `APP_DATABASE_URL` / `APP_MEDIA_ROOT`。 + +**compose 里的 `comfyui` 服务默认不参与**:它带 `profiles: ["comfy"]`, +`docker compose up -d` 只起 `app` 一个容器(`docker compose config --services` 可验证)。 +你的 ComfyUI 在算力机上,靠「模型中心」里的 `base_url` 连过去,跟这个 profile 无关; +它只是「算力恰好装在同一台机器、想用容器跑一份 ComfyUI」时的备选开关。 + 镜像里是**后端代码 + 前端构建产物 + ffmpeg**(两段式:node 阶段 `npm ci && npm run build`, 运行阶段 `python:3.12-slim` 装 ffmpeg 与 pip 依赖)。库用 SQLite、任务用 `TASK_EXECUTOR=inline`, 也就是 §3.1 那套单机形态——**没有 nginx 容器、没有 Redis、没有独立 worker/beat**: @@ -346,7 +359,7 @@ docker compose up -d | 对外端口 | **就一个键:`.env` 里的 `PORT`**,Docker 的对外映射、裸机 `server.sh` 的监听、开发态的后端全都读它。容器内固定 8000(与 `EXPOSE`/健康检查对齐),改 `PORT` 改的只是对外的映射;开发态另有一个 `FRONTEND_PORT`,因为 Vite 是独立进程。优先级 **命令行 `--port` > 环境变量 > `.env` > 默认 8000** | | 拉不到 docker.io / 装包慢 | `.env` 或 `--build-arg` 覆盖 `BASE_IMAGE`、`NODE_IMAGE`、`PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR`(apt 源,装 ffmpeg 那一层) | | 换 ComfyUI / 换 GPU 机 | **不在 `.env` 里改**:登录页面「调度中心 → 模型中心」,改那几条模型的 `base_url` 并点 🔌 探测,改完即生效、不用重启。指宿主机写 `http://host.docker.internal:9200`(`extra_hosts` 已备 `host-gateway`),写 `127.0.0.1` 指向的是容器自己 | -| 顺带起一个自建 ComfyUI | `docker compose --profile comfy up -d`,再把 `base_url` 指 `http://comfyui:8188` | +| 顺带起一个自建 ComfyUI | `docker compose --profile comfy up -d`(默认**不起**,算力在远端时不用管),再把 `base_url` 指 `http://comfyui:8188` | 拉不到 docker.io 时不用改 Dockerfile,把两个基础镜像指到能通的 registry 就行(本机实测可用, `npm ci`/`apt`/`pip` 三段源都能在 `.env` 里换(`NPM_REGISTRY` / `APT_MIRROR=mirrors.tuna.tsinghua.edu.cn` / @@ -419,8 +432,9 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \ ``` `install` 首次生成的 `.env` 是**单机版**(SQLite + `TASK_EXECUTOR=inline` + `SERVE_FRONTEND=on`), -不是 `cp .env.example`——模板里那套是 Postgres + Redis + Celery 的容器形态,直接 cp 会因为 -连不上 DB/Redis 而起不来。`inline` 的调度守护线程跑在进程内,所以服务形态**固定单进程**, +只写跑起来必需的那几行;`.env.example` 现在也是同一套默认值,所以 `cp` 一份裸跑同样起得来, +两种写法等价,差的是注释多寡和键的多少(旧版模板默认 Postgres + Celery,cp 过去会因为 +连不上 DB/Redis 而起不来,那个坑已经填了)。`inline` 的调度守护线程跑在进程内,所以服务形态**固定单进程**, 加 `--workers` 等于 N 份守护线程抢同一批任务重复派发;要横向扩展就切 `celery` 另起 worker。 **部署包里只有代码,没有你跑出来的内容**(`deploy.sh` 逐条体检,缺的多的直接 die): diff --git a/docker-compose.yml b/docker-compose.yml index f06fc59..950d3b9 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,7 +5,8 @@ # docker compose up -d --build 首次部署(构建 + 后台启动) # docker compose logs -f app 看日志(首启会打印「导入部署数据包」那一行) # docker compose ps 状态(healthy 才算起来) -# docker compose restart app 改了 .env 之后重启生效(改模型配置不用重启) +# docker compose up -d 改了 .env 之后重跑这条:端口映射是在创建容器时定下的, +# restart 沿用旧容器配置,改了 PORT 也不会换端口 # docker compose down 停止并删除容器,数据留在 ./data 与 ./media # 打开 http://localhost:8000 默认账号见 BOOTSTRAP_USERNAME / BOOTSTRAP_PASSWORD #