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 #