diff --git a/.env.example b/.env.example index 8ced0fb..5603a24 100644 --- a/.env.example +++ b/.env.example @@ -1,116 +1,50 @@ # ============================================================ -# Nex Animation Studio · 运行时配置(复制为 .env 后按需修改) -# · .env 是「每台机器一份」的配置:它不进仓库,服务器上的那份由你从本文件复制, -# 跟开发机那份互不影响。部署包也不带它——先 cp 再改,是唯一需要编辑的文件。 -# · 应用配置项 = backend/app/config.py 里 Settings 字段的大写下划线形式(多余键忽略) -# · 端口优先级:命令行参数 > 环境变量 > 本文件的 PORT -# · 模型配置不在这里:地址、模型名、步数、超时、并发与限流、单价、默认位都在数据库, -# 页面「调度中心 → 模型中心」,服务器上的初值随部署包 scripts/seed/ 导入 +# 复制为 .env 后按需修改(每台机器一份,不进仓库;模型配置在页面「调度中心 → 模型中心」) +# 这份文件只放配置本身,为什么这么配见 README §3(部署)与 docs/工程规范.md §5 # ============================================================ # ---------- 端口 ---------- -# 应用对外端口只有一个,三种形态共用:Docker 对外的映射、裸机 server.sh 监听的、开发态的后端 -# 都读它。容器内固定监听 8000(与 EXPOSE / HEALTHCHECK 对齐),改这里只改对外映射。 -PORT=8000 -# 仅开发形态需要第二个端口:Vite 是独立进程,必须和后端错开 -FRONTEND_PORT=5173 +HOST_PORT=8000 # 部署形态对外暴露的端口:Docker 的映射、裸机 server.sh 的监听(容器内固定 8000) +BACKEND_PORT=8000 # 开发形态:后端 uvicorn(scripts/dev.sh) +FRONTEND_PORT=5173 # 开发形态:前端 Vite(scripts/dev.sh,独立进程,必须与后端错开) -# ---------- Docker 构建与首启(compose 读,应用不读)---------- -# AUTO_SEED:首启导入 scripts/seed 数据包的方式 only-missing(默认)| force | off -# APP_DATABASE_URL / APP_MEDIA_ROOT:容器内的库与产物路径,必须落在挂载点里 -# (./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 -# PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple -# NPM_REGISTRY=https://registry.npmmirror.com -# POSTGRES_* / CELERY_CONCURRENCY 只在叠加 docker-compose.scale.yml 时用到 - -# ---------- 存储 ---------- -# 这两行是「不带 compose 裸跑」时的取值(相对路径锚定仓库根); -# Docker 形态下 compose 把它们覆盖成 APP_DATABASE_URL / APP_MEDIA_ROOT 那两个挂载点。 -# 产物落在容器可写层的后果是下次重建镜像就没了,所以容器里必须是挂载点内的绝对路径。 -DATABASE_URL=sqlite:///./nex_animation.db -MEDIA_ROOT=./media +# ---------- 基础设施 ---------- +DATABASE_URL=sqlite:///./nex_animation.db # Docker 形态下 compose 会指到挂载点 ./data +MEDIA_ROOT=./media # 同上,容器内为 ./media 挂载点 MEDIA_URL_PREFIX=/media CORS_ORIGINS=* LOG_LEVEL=INFO -# ---------- 鉴权与账号 ---------- -# 开启时 /api/* 与 /media/* 都要会话;关掉只适合可信内网(任何人都能裸奔写入)。 -AUTH_ENABLED=true -BOOTSTRAP_USERNAME=admin -BOOTSTRAP_PASSWORD=admin1234 -# COOKIE_NAME=nex_session - -# ---------- 前端托管 + 任务执行后端(默认 = 单容器那一套)---------- -# on = 后端一并托管 frontend/dist 并做 SPA history 回落,对外只有一个端口 -# inline = 进程内线程池 + 内置派发守护,不需要 Redis -SERVE_FRONTEND=on -# FRONTEND_DIST_DIR= # 留空 = <仓库根>/frontend/dist -TASK_EXECUTOR=inline +# ---------- 任务执行后端 ---------- +TASK_EXECUTOR=inline # inline 进程内线程池(无需 Redis);celery 见 docker-compose.scale.yml INLINE_WORKERS=2 -# ---------- 扩容层专用:只在 -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 -# CELERY_CONCURRENCY=2 +# ---------- 鉴权与账号 ---------- +AUTH_ENABLED=true +BOOTSTRAP_USERNAME=admin +BOOTSTRAP_PASSWORD=admin1234 # 库里首个管理员,登录后请立刻改口令 # ---------- 调度节奏 / 重试 / 断点续跑 ---------- DISPATCH_INTERVAL_SECONDS=5 DISPATCH_BATCH_SIZE=32 -MAX_SHOT_RETRIES=3 +MAX_SHOT_RETRIES=2 MAX_COMPOSE_RETRIES=2 RETRY_BACKOFF_BASE_SECONDS=5 RETRY_BACKOFF_MAX_SECONDS=300 -# 僵死判定要比「最慢的正常任务」更宽,否则会把正在跑的镜头抢回来重跑 -STALE_RUNNING_SECONDS=900 -# 新建一条模型没填限额时的初始值 +STALE_RUNNING_SECONDS=1800 # 要比最慢的正常出图更宽,否则会把在跑的镜头抢回来重跑 DEFAULT_PROVIDER_CONCURRENCY=2 DEFAULT_PROVIDER_RPM=30 -# ---------- 合成引擎 ---------- +# ---------- 合成与质检 ---------- DEFAULT_FPS=24 DEFAULT_WIDTH=1920 DEFAULT_HEIGHT=1080 TARGET_LUFS=-16.0 -XFADE_MAX_DURATION_MS=1200 -FFMPEG_THREADS=0 -FFMPEG_PRESET=medium -FFMPEG_CRF=20 -# 留空 = 自动探测(优先挑带 libass 的完整版构建,能烧字幕);填绝对路径可强制指定 -# FFMPEG_BIN= -# FFPROBE_BIN= - -# ---------- 自动质检阈值 ---------- QC_DURATION_TOLERANCE=0.35 QC_MIN_BITRATE_KBPS=200 -QC_BLACK_THRESHOLD=0.98 QC_VISUAL_ENABLED=true -QC_VISUAL_FRAMES=4 -QC_VISUAL_REFERENCES=3 -QC_VISUAL_WEIGHT=0.4 QC_ASR_ENABLED=true -# 本地听写权重是文件路径,./scripts/server.sh install 会自动下载(--no-asr 跳过) -ASR_MODEL=models/asr/ggml-small.bin +ASR_MODEL=models/asr/ggml-small.bin # 本地听写权重,server.sh install 自动下载 # ---------- 成本台账 ---------- COST_CURRENCY=CNY - -# ---------- 上传白名单(一般无需修改)---------- -# UPLOAD_IMAGE_EXTENSIONS=.png,.jpg,.jpeg,.webp,.gif,.bmp,.tif,.tiff -# UPLOAD_VIDEO_EXTENSIONS=.mp4,.mov,.webm,.mkv,.m4v,.avi -# UPLOAD_AUDIO_EXTENSIONS=.mp3,.wav,.m4a,.aac,.flac,.ogg,.opus -# UPLOAD_DOC_EXTENSIONS=.txt,.md,.csv,.tsv,.json,.srt,.ass,.vtt,.zip,.docx diff --git a/README.md b/README.md index d5d7279..5dd6d51 100644 --- a/README.md +++ b/README.md @@ -290,7 +290,7 @@ cd frontend && npm install && npm run dev # http://localhost:5173 > 校验 `typeof health.status === 'string'`,一旦代理缺失直接抛出可读错误而不是假装健康。 > > **后端换地址/换端口**:手工起前端用 `NEX_BACKEND=http://127.0.0.1:8010 npm run dev`,无需改代码; -> 用 `./scripts/dev.sh` 的话改 `.env` 里 `PORT` 就行,脚本会把代理目标一起带着走。 +> 用 `./scripts/dev.sh` 的话改 `.env` 里 `BACKEND_PORT` 就行,脚本会把代理目标一起带着走。 > **SQLite 路径**的父目录由 `app/db.py` 自动创建,`DATABASE_URL='sqlite://////tmp/nex_ui/ui.db'` > 可直接使用(注意 SQLite URL 是 6 个斜杠:3 个协议分隔 + 绝对路径根)。 @@ -298,18 +298,31 @@ cd frontend && npm install && npm run dev # http://localhost:5173 ```bash cp .env.example .env # 或直接复用开发机那份:compose 会把 .env 整份注入容器 -docker compose up -d --build # 只起一个容器 nex-animation,对外只有 .env 里的 PORT(默认 8000) +docker compose up -d --build # 只起一个容器 nex-animation,对外端口 = .env 的 HOST_PORT(默认 8000) docker compose logs -f app # 首启会打印「导入部署数据包:seed.py install --only-missing」 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`。 +**`.env` 是「每台机器一份」的文件**:仓库根那份是你开发机的配置(SQLite、开发端口、本机口令), +它 gitignored、不在部署包里;服务器上是 `cp .env.example .env` 生成的另一份。**对外暴露的端口就配在 +服务器那份 `.env` 的 `HOST_PORT=` 一行**,不在 compose 文件里(compose 只引用它:先替 `${HOST_PORT}` +插值得到 `ports` 映射,再把整份 `.env` 注入容器当环境变量)。容器内永远监听 8000,改 `HOST_PORT` +改的只是对外的映射,而且**必须重跑 `docker compose up -d`**——`restart` 沿用旧容器配置,不换端口。 +`.env` 里还有四行在 Docker 形态下改了没反应:`DATABASE_URL`、`MEDIA_ROOT`、`SERVE_FRONTEND`、 +`TASK_EXECUTOR` 被 compose 的 `environment` 覆盖(所以模板里干脆不写后两条,要挪容器内的落点改 +`APP_DATABASE_URL` / `APP_MEDIA_ROOT`)。 + +**端口一共三个键,按形态分,别混用**: + +| 键 | 管谁 | 谁读它 | +| --- | --- | --- | +| `HOST_PORT` | **部署形态**对外的端口:Docker 的端口映射、裸机 `server.sh` 的监听 | compose 插值 / `server.sh` 回读 | +| `BACKEND_PORT` | **开发形态**的后端 uvicorn | `dev.sh` 回读(并同步 Vite 代理目标) | +| `FRONTEND_PORT` | **开发形态**的前端 Vite(独立进程,必须与后端错开) | `dev.sh` 回读 | + +取值优先级统一是 **命令行参数 > 同名环境变量 > `.env` > 默认值**(`server.sh` 是 `--port`, +`dev.sh` 是 `--backend-port` / `--frontend-port`)。开发机与容器同机时记得错开 `HOST_PORT`, +本仓开发机用的是 `HOST_PORT=8010`,因为 8000 坐着开发后端。 **compose 里的 `comfyui` 服务默认不参与**:它带 `profiles: ["comfy"]`, `docker compose up -d` 只起 `app` 一个容器(`docker compose config --services` 可验证)。 @@ -356,7 +369,7 @@ docker compose up -d | 想改什么 | 改哪里 | | --- | --- | -| 对外端口 | **就一个键:`.env` 里的 `PORT`**,Docker 的对外映射、裸机 `server.sh` 的监听、开发态的后端全都读它。容器内固定 8000(与 `EXPOSE`/健康检查对齐),改 `PORT` 改的只是对外的映射;开发态另有一个 `FRONTEND_PORT`,因为 Vite 是独立进程。优先级 **命令行 `--port` > 环境变量 > `.env` > 默认 8000** | +| 对外端口 | **`.env` 里的 `HOST_PORT`**(部署形态:Docker 的映射、裸机 `server.sh` 的监听都读它)。容器内固定 8000,改 `HOST_PORT` 改的只是对外映射,且要重跑 `up -d`;开发形态另用 `BACKEND_PORT` / `FRONTEND_PORT`,详见 §3.2 的端口表 | | 拉不到 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` | @@ -424,7 +437,7 @@ React Router 的 history 回退已经处理好(地址栏直接刷 `/projects/3 # ---- 服务器:落地 ---- tar -xzf nex_animation-*.tar.gz && cd nex_animation ./scripts/server.sh install # venv + 依赖 + npm build + 听写模型 + 体检 + 建表灌种子数据 -./scripts/server.sh start # 单进程 uvicorn;端口取 .env 的 PORT(默认 :8000,--port 覆盖) +./scripts/server.sh start # 单进程 uvicorn;端口取 .env 的 HOST_PORT(默认 :8000,--port 覆盖) ./scripts/server.sh verify # 图2 全 12 节点真实 HTTP + ffprobe 自检 ./scripts/server.sh status # 端口 / 健康 / 默认模型 / ComfyUI 连通性 / 数据边界 sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \ diff --git a/docker-compose.yml b/docker-compose.yml index 950d3b9..10b7498 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,36 +1,18 @@ # ============================================================================= -# Nex Animation Studio · 部署编排(单容器整站:后端 + 前端产物 + SQLite + 进程内调度) +# Nex Animation Studio · 单容器部署(后端 + 前端产物 + ffmpeg 在同一个镜像里) # -# 日常命令: +# 常用命令: # docker compose up -d --build 首次部署(构建 + 后台启动) -# docker compose logs -f app 看日志(首启会打印「导入部署数据包」那一行) -# docker compose ps 状态(healthy 才算起来) -# docker compose up -d 改了 .env 之后重跑这条:端口映射是在创建容器时定下的, -# restart 沿用旧容器配置,改了 PORT 也不会换端口 +# docker compose logs -f app 看日志(首启会打印导入数据包那一行) +# docker compose ps 状态(healthy 才算起来,探的是 /health) +# docker compose up -d 改了 .env 之后重跑这条:restart 沿用旧容器配置,不换端口映射 # docker compose down 停止并删除容器,数据留在 ./data 与 ./media -# 打开 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 库(几 MB~几百 MB) ← 唯一会被写坏的目录,值得单独备份 -# ./media 出片产物与上传素材(只涨不跌) ← 单独一个挂载点:能整目录挪大盘、 -# 能被 rsync/剪辑软件直接读, -# 和库分开才敢单独做备份与迁移 -# ./scripts/seed 模型配置 + 加密主密钥 + 管理员 ← gitignored 的机密,所以不进镜像层 -# ./models whisper 权重等(可选) -# 容器首启由 scripts/docker-entrypoint.sh 拿 seed 目录把库灌好(AUTO_SEED 控制)—— -# 「用哪个模型、地址是什么」就是这么进库的,不是从 .env 读的。 -# -# 配置来源:同目录 .env(compose 会替变量插值读它,并整份注入容器)。 -# 下面 environment 里点名的键是例外——容器里的路径和宿主机不是一回事,必须覆盖。 -# .env 里不再放模型配置(VIDEO_* / COMFYUI_* / TTS_*),换 ComfyUI 地址去页面改。 +# 配置来源:同目录 .env(compose 既用它做变量插值,也整份注入容器)。 +# 对外端口 = .env 的 HOST_PORT;容器内固定监听 8000(与 EXPOSE / HEALTHCHECK 对齐)。 +# 下面 environment 点名的键是例外,容器内的路径与宿主不是一回事,必须覆盖。 +# 数据四个 bind mount:./data 库、./media 产物、./scripts/seed 模型配置与主密钥、./models 权重。 +# 为什么只要一个容器、模型配置为什么不在这份文件里、扩容层怎么叠:README §3.2 与 §4.0。 # 需要 Docker Compose ≥ v2.24(env_file 的 required: false 写法)。 # ============================================================================= name: nex-animation @@ -40,59 +22,40 @@ services: build: context: . args: - # 基础镜像与 pip/npm 源都可以在 .env 里覆盖:直连 docker.io / npmjs 很慢时先探好再构建 + # 源与基础镜像可在 .env 里覆盖,默认值就按国内直连能通的配 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}" - # apt 源只有装 ffmpeg 这一层用得到;默认官方源,国内服务器直连不动时再覆盖 APT_MIRROR: "${APT_MIRROR:-deb.debian.org}" image: nex-animation:latest container_name: nex-animation restart: unless-stopped env_file: - path: .env - required: false # 空机器上先起来再配模型,别让缺 .env 变成起不来 + required: false # 空机器上先起来再配,别让缺 .env 变成起不来 environment: - # ---- 容器内路径:宿主 .env 里写的是 ./media、./nex_animation.db,直接透传会漂 ---- - # 库落 ./data,产物落 ./media:两个挂载点各管各的,理由见文件头与 Dockerfile。 DATABASE_URL: "${APP_DATABASE_URL:-sqlite:////app/data/nex_animation.db}" MEDIA_ROOT: "${APP_MEDIA_ROOT:-/app/media}" - # ---- 容器内永远监听 8000:端口一节写的 PORT 是「对外映射到哪个端口」, - # 不是容器里的监听端口(EXPOSE 与健康检查都按 8000 写死)。显式覆盖宿主 .env - # 注进来的那份,免得将来谁让应用直接读 PORT 时监听端口跟着漂。 - PORT: "8000" - # ---- 整站形态的两把开关:后端托管前端 + 进程内执行后端,都必须在容器里成立 ---- - SERVE_FRONTEND: "on" - TASK_EXECUTOR: "inline" + SERVE_FRONTEND: "on" # 后端托管 frontend/dist,对外只有一个端口 + TASK_EXECUTOR: "inline" # 进程内线程池 + 派发守护线程,不需要 Redis 与独立 worker 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}" + AUTO_SEED: "${AUTO_SEED:-only-missing}" # 首启用 scripts/seed 灌模型配置:only-missing|force|off TZ: "${TZ:-Asia/Shanghai}" - # 这里刻意没有 COMFYUI_BASE_URL / VIDEO_PROVIDER / TTS_*:模型端点存在数据库里 - # (model_specs.base_url / config_json),改完立刻生效,不需要重启容器, - # 也不需要「改 .env + 改页面」两处对齐。页面路径:调度中心 → 模型中心。 ports: - # 对外只有这一个端口:.env 的 PORT(HOST_PORT 是旧键,兼容一版) - - "${PORT:-${HOST_PORT:-8000}}:8000" + - "${HOST_PORT:-8000}:8000" volumes: - ./data:/app/data - ./media:/app/media - ./scripts/seed:/app/scripts/seed:ro - ./models:/app/models:ro extra_hosts: - # Linux 上没有内建的 host.docker.internal,靠 host-gateway 指回宿主机。 - # 自建 ComfyUI 装在宿主机时,模型中心里的 base_url 要写 http://host.docker.internal:9200 - # (写 127.0.0.1 指向的是容器自己);装在局域网另一台机器就写那台的实际 IP,本条不影响。 - - "host.docker.internal:host-gateway" + - "host.docker.internal:host-gateway" # 自建 ComfyUI 装宿主机时用它指回宿主 - # 自建 ComfyUI(可选):docker compose --profile comfy up -d 起一份容器实例。 - # 已有外部 GPU 机(例如 http://10.100.53.199:9200)时不用开它, - # 去「调度中心 → 模型中心」把三条 comfyui 模型的 base_url 改过去就行(改完即生效,无需重启); - # 装在宿主机上的话用 http://host.docker.internal:9200,指本 profile 起的容器用 http://comfyui:8188。 + # 可选:在本机用容器起一份 ComfyUI。默认不参与(--profile comfy 才起),算力在远端时不用管。 comfyui: profiles: ["comfy"] image: comfyanonymous/comfyui:latest diff --git a/docs/工程规范.md b/docs/工程规范.md index 4aaf7af..16aedf1 100644 --- a/docs/工程规范.md +++ b/docs/工程规范.md @@ -181,10 +181,15 @@ ffmpeg 与本地听写权重)。判据是一句话:**换模型要不要重 即视为回归(`app/config.py` 仍保留这些字段,但它们是空库自检的代码级兜底,不是配置入口)。 `.env` 里**只写配置本身**:一个键最多跟一行注释,「为什么不在这里」的长篇理由写在 README 与 本节,不写进 `.env`(那份文件是运维唯一被要求编辑的,注释比配置长就没人读完它)。 -写进去的键必须有明确的读取方,且**一件事只有一个键**:端口全项目就 `PORT` 一个——compose 拿它做 -对外映射、`server.sh` 拿它做监听端口、`dev.sh` 拿它当开发态后端端口(只有 Vite 因为是独立进程额外 -要 `FRONTEND_PORT`)。同义键是回归:曾经 `HOST_PORT` / `PORT` / `BACKEND_PORT` 三个键指同一个端口, -运维改哪个都不确定是不是改对了。优先级统一是 **命令行 > 环境变量 > `.env` > 代码默认值**。 +写进去的键必须有明确的读取方,而且**一个键只能有一种含义、同一个 socket 不能有两个键**。 +端口按形态分三个键,键名自带它的适用场景:`HOST_PORT` = 部署形态对外的端口(compose 插值做端口映射、 +`server.sh` 回读做监听),`BACKEND_PORT` / `FRONTEND_PORT` = 开发形态的两个进程(`dev.sh` 回读)。 +反面例子是两个版本里都出现过:先是有过 `HOST_PORT` / `PORT` / `BACKEND_PORT` 三个键指同一件事 +(改哪个都不确定对不对),随后收敛成一个 `PORT` 又被三种形态共用(同一个键在 Docker 下指对外映射、 +在裸机下指监听、在开发下指后端,不读 README 的人分不出来)。判据从来不是键的个数,是含义的唯一性。 +优先级统一是 **命令行 > 环境变量 > `.env` > 代码默认值**,两个脚本都回读 `.env`——写在里面却没人读的键 +同样是回归(`.env.example` 因此不再列 `SERVE_FRONTEND` 与 Postgres/Redis/Celery 那一组:前者在 Docker +形态被 compose 覆盖,后者只在叠加 `docker-compose.scale.yml` 时有人读)。 | 内容 | 怎么到新机器上 | |---|---| diff --git a/scripts/dev.sh b/scripts/dev.sh index 09d652c..b78bcef 100755 --- a/scripts/dev.sh +++ b/scripts/dev.sh @@ -43,17 +43,19 @@ esac # 本机局域网 IP(macOS:默认路由网卡 → ipconfig getifaddr),取不到就只打印回环地址。 LAN_IP="$( { iface="$(route -n get default 2>/dev/null | awk '/^[[:space:]]*interface:/{print $2; exit}')" [ -n "$iface" ] && ipconfig getifaddr "$iface" 2>/dev/null; } || true )" -env_value() { # 从仓库根 .env 读一个键(最后一行为准,去引号/去空白) +env_value() { # 从仓库根 .env 读一个键(最后一行为准;去引号、去随行注释、去尾部空白) [ -f "$ROOT/.env" ] || return 0 - sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 | tr -d '\r"'"'"'' || true + sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 \ + | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//' | tr -d '\r"'"'"'' || true } -# 全项目只有 PORT 这一个端口键,开发态的后端就是它(Vite 是独立进程,才需要 FRONTEND_PORT -# 这第二个端口)。取值优先级:命令行 --backend-port/--frontend-port > 同名环境变量 > .env > 默认值, -# 和 scripts/server.sh 是同一条约定:.env 是运维唯一被要求编辑的文件,写进去的必须真的生效 +# 开发形态两个进程各一个键:BACKEND_PORT(uvicorn)/ FRONTEND_PORT(Vite)。 +# 部署形态的对外端口是另一个键 HOST_PORT,跟这里无关(见 .env.example 的端口一节)。 +# 取值优先级:命令行 --backend-port/--frontend-port > 同名环境变量 > .env > 默认值, +# 和 scripts/server.sh 是同一条约定:.env 写进去的键必须真的生效 # (后端换端口时下面还会把 NEX_BACKEND 一起带着走,代理不会掉队)。 -BACKEND_PORT="${BACKEND_PORT:-${PORT:-$(env_value PORT)}}" -BACKEND_PORT="${BACKEND_PORT:-$(env_value BACKEND_PORT)}" # 旧键兼容 +BACKEND_PORT="${BACKEND_PORT:-$(env_value BACKEND_PORT)}" +BACKEND_PORT="${BACKEND_PORT:-$(env_value PORT)}" # 旧键兼容 BACKEND_PORT="${BACKEND_PORT:-8000}" FRONTEND_PORT="${FRONTEND_PORT:-$(env_value FRONTEND_PORT)}" FRONTEND_PORT="${FRONTEND_PORT:-5173}" diff --git a/scripts/server.sh b/scripts/server.sh index 18a9c26..be8bf01 100755 --- a/scripts/server.sh +++ b/scripts/server.sh @@ -40,18 +40,20 @@ RUN_DIR="$ROOT/.local/run" LOG_DIR="$ROOT/.local/logs" PYBIN="$ROOT/.venv/bin/python" NAME=server -env_value() { # 从仓库根 .env 读一个键(最后一行为准,去引号/去空白) +env_value() { # 从仓库根 .env 读一个键(最后一行为准;去引号、去随行注释、去尾部空白) [ -f "$ROOT/.env" ] || return 0 - sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 | tr -d '\r"'"'"'' || true + sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 \ + | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//' | tr -d '\r"'"'"'' || true } HOST="${NEX_HOST:-0.0.0.0}" -# 全项目只有 PORT 这一个端口键:Docker 对外的映射、开发态的后端也都读它(见 .env.example)。 -# 取值优先级:命令行 --port > 环境变量 PORT > .env 里的 PORT > 8000。 -# 回读 .env 是有意的:运维习惯把端口写进 .env(那是他唯一被要求编辑的文件), -# 而以前这里只认命令行与环境变量,表现就是「.env 明明改了 9000,服务还在 8000」。 -PORT="${PORT:-$(env_value PORT)}" -PORT="${PORT:-$(env_value HOST_PORT)}" # 旧键:早期 .env.example 让裸机也写 HOST_PORT +# 部署形态的对外端口只有一个键:HOST_PORT(Docker 的端口映射、裸机监听的都读它)。 +# 开发态的 BACKEND_PORT / FRONTEND_PORT 是另一码事,别混用(见 .env.example 的端口一节)。 +# 取值优先级:命令行 --port > 环境变量 HOST_PORT/PORT > .env 的 HOST_PORT > 8000。 +# 回读 .env 是有意的:.env 是运维唯一被要求编辑的文件,写进去的键必须真的生效, +# 否则表现就是「.env 明明改了 9000,服务还在 8000」。 +PORT="${HOST_PORT:-${PORT:-$(env_value HOST_PORT)}}" +PORT="${PORT:-$(env_value PORT)}" # 旧键兼容:上一版模板这里叫 PORT PORT="${PORT:-8000}" ASR_MODEL="$ROOT/models/asr/ggml-small.bin" ASR_URL="https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin" @@ -175,8 +177,8 @@ ensure_env() { # 改完重启生效:./scripts/server.sh restart # 模型配置不在这里:库里的「调度中心 → 模型中心」改,改完即生效,不用重启服务。 -# ---- 端口:本服务对外监听的端口(restart 后生效)---- -PORT=8000 +# ---- 端口:对外暴露的端口(restart 后生效)---- +HOST_PORT=8000 # ---- 存储:单机用 SQLite,媒体落 ./media ---- DATABASE_URL=sqlite:///./nex_animation.db