把「服务器上那份 .env 到底管什么」写死:模板默认改成单容器真相,compose 覆盖的键逐条点名

部署前必问的三个问题,答案以前都藏在别的文件里,这次直接写进 .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。
main
mula.liu 2026-11-05 18:52:38 +08:00
parent 1934fb8bcc
commit 24978e9843
3 changed files with 44 additions and 24 deletions

View File

@ -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

View File

@ -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):

View File

@ -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
#