diff --git a/.dockerignore b/.dockerignore index 2a6ce64..2a38625 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,6 +5,7 @@ .env .env.* !.env.example +docker-compose.override.yml # Python 缓存 **/__pycache__ diff --git a/.env.example b/.env.example index c8acc47..5a6ec9b 100644 --- a/.env.example +++ b/.env.example @@ -10,10 +10,10 @@ BACKEND_PORT=8100 FRONTEND_PORT=5174 # ---- 数据库 ---- -DATABASE_URL=postgresql+asyncpg://postgres:sagacity@192.168.124.203:5432/nex_buddy +DATABASE_URL=postgresql+asyncpg://postgres:sagacity@127.0.0.1:5432/nex_buddy # ---- 缓存 ---- -REDIS_URL=redis://192.168.124.203:6379/9 +REDIS_URL=redis://127.0.0.1:6379/9 # ---- 和风天气 ---- # Key 直接可用;Host 是账号专属的,登录控制台 → 设置 复制(形如 abc1234xyz.re.qweatherapi.com) @@ -28,23 +28,10 @@ WEATHER_CACHE_SECONDS=1800 DEFAULT_CITY=杭州 # ---- 资源目录 ---- -# 默认是项目根 data/;服务器/容器部署可指向宿主机挂载点 +# 裸机/systemd 部署用:默认是项目根 data/。 +# Docker 部署固定使用容器内 /app/data,由 docker-compose.yml 挂载,不需要在这里配置。 # DATA_DIR=/srv/nex_buddy/data -# ---- Docker 部署(可选) ---- -# 宿主机资源目录(Compose 挂载到容器 /app/data),默认 ./data -# NEX_BUDDY_DATA_DIR=/srv/nex_buddy/data -# Web 对外端口,默认 80 -# HTTP_PORT=80 -# 仅 docker-deploy.sh --full 使用;请务必改掉默认口令 -# POSTGRES_DB=nex_buddy -# POSTGRES_USER=nex_buddy -# POSTGRES_PASSWORD=change-me -# 构建加速(默认已用国内源,可覆盖) -# PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple -# APT_MIRROR=mirrors.tuna.tsinghua.edu.cn -# NPM_REGISTRY=https://registry.npmmirror.com - # ---- CORS(一般不用配) ---- # Web 与 API 同域部署(Nginx 反代 / 已配 WEB_BASE_URL)时不需要 CORS, # 保持不设置即可。只有 Web 与 API 确实不同域时才需要: diff --git a/.gitignore b/.gitignore index f127dc3..a853fa1 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ build/ .env .env.* !.env.example +docker-compose.override.yml # ---- 运行时资源 ---- # data/ 下是用户上传与固件包,默认不入库; diff --git a/README.md b/README.md index f5bf511..50c2188 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,9 @@ sudo nginx -t && sudo systemctl reload nginx ```bash cp .env.example .env # APP_ENV=prod;外部 DB/Redis 填 DATABASE_URL / REDIS_URL -# 资源目录默认 ./data,也可 NEX_BUDDY_DATA_DIR=/srv/nex_buddy/data + +# 服务器差异项(基础镜像、构建源、端口、宿主机挂载路径)放这里 +cp docker-compose.override.example.yml docker-compose.override.yml ./scripts/docker-deploy.sh # 已有 PG/Redis ./scripts/docker-deploy.sh --full --init # 连 PG/Redis 一起起,并初始化码表 @@ -95,9 +97,12 @@ docker compose exec api python server/scripts/create_admin.py \ ``` - `data/` 会挂载到容器 `/app/data`,媒体、固件、码表都在这里。 -- 构建阶段 pip / npm / apt 默认走国内源,可用 `PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR` 覆盖; +- `.env` 只放应用运行配置;构建源、端口、挂载路径都放 `docker-compose.override.yml`。 +- 构建阶段 pip / npm / apt 默认走国内源,可在 override 文件里覆盖; `docker pull` 的镜像加速见 `docker/README.md`。 -- `--full` 时先在 `.env` 修改 `POSTGRES_PASSWORD`,不要用默认口令。 +- Dockerfile 不再使用 `# syntax=docker/dockerfile:1`;`PYTHON_IMAGE` / `NODE_IMAGE` / `NGINX_IMAGE` + 可指向服务器本地已有镜像或私有仓库,避免额外访问 Docker Hub。 +- `--full` 时用环境变量传口令:`POSTGRES_PASSWORD='强口令' ./scripts/docker-deploy.sh --full --init`。 --- @@ -109,6 +114,7 @@ nex_buddy/ ├── .dockerignore ├── docker-compose.yml API + Web(外部 DB/Redis) ├── docker-compose.full.yml 可选:同时启动 PostgreSQL + Redis +├── docker-compose.override.example.yml 服务器差异项模板(基础镜像/源/端口/挂载) ├── docker/ 镜像、Nginx、entrypoint 与 Docker 说明 ├── scripts/ 启动 / 部署 / systemd / Nginx 脚本 ├── data/ 运行时资源:regions.json + media/ + firmware/(媒体与固件不入库) diff --git a/docker-compose.override.example.yml b/docker-compose.override.example.yml new file mode 100644 index 0000000..ee2b04e --- /dev/null +++ b/docker-compose.override.example.yml @@ -0,0 +1,30 @@ +# 复制为 docker-compose.override.yml 后按需修改;该文件不入库。 +# +# cp docker-compose.override.example.yml docker-compose.override.yml +# +# docker-deploy.sh 与 docker compose 会自动带上这个覆盖文件。 + +services: + api: + build: + args: + # 基础镜像:可改成服务器本地已有镜像或私有仓库地址 + PYTHON_IMAGE: python:3.12-slim + # 国内依赖源 + APT_MIRROR: mirrors.tuna.tsinghua.edu.cn + PIP_INDEX_URL: https://pypi.tuna.tsinghua.edu.cn/simple + volumes: + # 宿主机资源目录 -> 容器 /app/data + - /srv/nex_buddy/data:/app/data + + web: + build: + args: + NODE_IMAGE: node:20-alpine + NGINX_IMAGE: nginx:1.27-alpine + NPM_REGISTRY: https://registry.npmmirror.com + # 对外端口默认 80。改 docker-compose.yml 的 web.ports, + # 或运行时指定 HTTP_PORT=8080(见 docker/README.md)。 + + # 使用 --full 时,PostgreSQL 口令通过 shell 环境变量传入更合适: + # POSTGRES_PASSWORD='强口令' ./scripts/docker-deploy.sh --full --init diff --git a/docker-compose.yml b/docker-compose.yml index 43dcde7..9d7712f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,21 +2,26 @@ name: nex-buddy services: api: + # 构建源与基础镜像默认值都在这里;服务器差异项建议写到 + # docker-compose.override.yml(可从 docker-compose.override.example.yml 复制)。 build: context: . dockerfile: docker/Dockerfile.api args: APT_MIRROR: "${APT_MIRROR:-mirrors.tuna.tsinghua.edu.cn}" PIP_INDEX_URL: "${PIP_INDEX_URL:-https://pypi.tuna.tsinghua.edu.cn/simple}" + PYTHON_IMAGE: "${PYTHON_IMAGE:-python:3.12-slim}" image: nex-buddy-api:latest init: true env_file: - .env environment: + # 容器内固定使用 /app/data,宿主机路径由下面的 volumes 决定 DATA_DIR: /app/data FORWARDED_ALLOW_IPS: "*" WEB_CONCURRENCY: "${WEB_CONCURRENCY:-2}" volumes: + # 默认挂载项目根 data/;要换宿主机磁盘就改这里或写 override 文件 - "${NEX_BUDDY_DATA_DIR:-./data}:/app/data" expose: - "8100" @@ -34,8 +39,11 @@ services: dockerfile: docker/Dockerfile.web args: NPM_REGISTRY: "${NPM_REGISTRY:-https://registry.npmmirror.com}" + NODE_IMAGE: "${NODE_IMAGE:-node:20-alpine}" + NGINX_IMAGE: "${NGINX_IMAGE:-nginx:1.27-alpine}" image: nex-buddy-web:latest ports: + # 对外端口默认 80;要换就改这里或写 override 文件 - "${HTTP_PORT:-80}:80" depends_on: api: diff --git a/docker/Dockerfile.api b/docker/Dockerfile.api index 4a13ec5..48619d1 100644 --- a/docker/Dockerfile.api +++ b/docker/Dockerfile.api @@ -1,5 +1,7 @@ -# syntax=docker/dockerfile:1 -FROM python:3.12-slim AS builder +# 基础镜像可通过 build arg 覆盖(例如使用本地已有镜像或私有仓库镜像)。 +ARG PYTHON_IMAGE=python:3.12-slim + +FROM ${PYTHON_IMAGE} AS builder # 国内构建加速:pip / apt 默认走清华源,可通过 build arg 覆盖。 ARG APT_MIRROR=mirrors.tuna.tsinghua.edu.cn @@ -30,7 +32,7 @@ RUN python -m pip install --upgrade pip --index-url "$PIP_INDEX_URL" \ && python -m pip install --prefix=/install -r requirements.txt --index-url "$PIP_INDEX_URL" -FROM python:3.12-slim AS runtime +FROM ${PYTHON_IMAGE} AS runtime ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ diff --git a/docker/Dockerfile.web b/docker/Dockerfile.web index 1e30cff..d130580 100644 --- a/docker/Dockerfile.web +++ b/docker/Dockerfile.web @@ -1,5 +1,8 @@ -# syntax=docker/dockerfile:1 -FROM node:20-alpine AS build +# 基础镜像可通过 build arg 覆盖(例如使用本地已有镜像或私有仓库镜像)。 +ARG NODE_IMAGE=node:20-alpine +ARG NGINX_IMAGE=nginx:1.27-alpine + +FROM ${NODE_IMAGE} AS build # npm 国内加速;可通过 build arg 覆盖。 ARG NPM_REGISTRY=https://registry.npmmirror.com @@ -14,7 +17,7 @@ COPY web/ ./ RUN npm run build -FROM nginx:1.27-alpine +FROM ${NGINX_IMAGE} COPY docker/nginx.conf /etc/nginx/conf.d/default.conf COPY --from=build /app/web/dist /usr/share/nginx/html diff --git a/docker/README.md b/docker/README.md index 0f91bba..9cc0f9d 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,5 +1,8 @@ # Docker 部署 +命令统一使用 Docker Compose v2 的 `docker compose`(带空格)。旧版 `docker-compose` +不支持本项目的顶层 `name` 与 `depends_on.condition` 写法,请先安装 Compose v2 插件。 + ## 文件 | 文件 | 用途 | @@ -10,10 +13,21 @@ | `docker/api-entrypoint.sh` | 启动前创建数据目录、补 `regions.json`、执行迁移 | | `docker-compose.yml` | API + Web;数据库/Redis 使用 `.env` 中的外部实例 | | `docker-compose.full.yml` | 可选覆盖:同时启动 PostgreSQL + Redis | +| `docker-compose.override.example.yml` | 服务器差异项模板:基础镜像、构建源、端口、挂载路径 | + +## 配置放哪里 + +- `.env`:只放应用运行配置,例如 `DATABASE_URL`、`REDIS_URL`、和风 Key、会话 TTL。 +- `docker-compose.yml`:构建源、基础镜像、默认端口与默认数据挂载。 +- `docker-compose.override.yml`:服务器差异项,从示例复制后修改,**不入库**。 + +```bash +cp docker-compose.override.example.yml docker-compose.override.yml +``` ## 国内下载加速 -构建参数默认已经改成国内源,也可以在 `.env` 或命令行覆盖: +构建参数默认已经改成国内源,可在 `docker-compose.override.yml` 或命令行覆盖: | 参数 | 默认值 | 用途 | |---|---|---| @@ -40,6 +54,30 @@ Docker 镜像本身不在这里配置;如果 `docker pull` 慢,在宿主机 镜像加速地址会变化,以当前可用的服务为准。 +## 基础镜像 + +Dockerfile 没有使用 `# syntax=docker/dockerfile:1`。这一行会额外从 Docker Hub 拉取 +BuildKit 前端镜像 `docker/dockerfile:1`,在只预加载了 `python:3.12-slim` 等业务基础镜像的 +服务器上仍可能因访问 Docker Hub 失败而报错。 + +三个基础镜像都可以通过构建参数替换成服务器本地已有镜像或私有仓库地址: + +| 参数 | 默认值 | +|---|---| +| `PYTHON_IMAGE` | `python:3.12-slim` | +| `NODE_IMAGE` | `node:20-alpine` | +| `NGINX_IMAGE` | `nginx:1.27-alpine` | + +```bash +PYTHON_IMAGE=python:3.12-slim \ +NODE_IMAGE=node:20-alpine \ +NGINX_IMAGE=nginx:1.27-alpine \ +docker compose build +``` + +如果本地镜像名称和默认值一致,Docker 会直接使用本地镜像;只有本地找不到时才会去 +Registry 拉取。基础镜像仍然建议配置 `registry-mirrors`,否则首次构建或镜像更新时还是要访问外网。 + ## 数据目录 容器内固定使用 `/app/data`,Compose 默认把宿主机 `./data` 挂进去: @@ -49,10 +87,27 @@ volumes: - "${NEX_BUDDY_DATA_DIR:-./data}:/app/data" ``` -所以在 `.env` 里写绝对路径即可把资源放到独立磁盘: +所以把 `docker-compose.override.yml` 的挂载路径改成独立磁盘即可: -```bash -NEX_BUDDY_DATA_DIR=/srv/nex_buddy/data +```yaml +services: + api: + volumes: + - /srv/nex_buddy/data:/app/data ``` 首次挂载空目录时,entrypoint 会把镜像内的 `regions.json` 复制进去;媒体和固件目录会自动创建。 + +Web 对外端口默认 80,可在 `docker-compose.yml` 的 `web.ports` 修改,或运行时指定: + +```bash +HTTP_PORT=8080 ./scripts/docker-deploy.sh +``` + +## 全栈数据库 + +`--full` 时建议用 shell 环境变量传 PostgreSQL 口令,不要把构建或部署参数塞回 `.env`: + +```bash +POSTGRES_PASSWORD='强口令' ./scripts/docker-deploy.sh --full --init +``` diff --git a/scripts/README.md b/scripts/README.md index 62d0bd6..e2cc295 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -42,17 +42,18 @@ sudo nginx -t && sudo systemctl reload nginx ## Docker ```bash +cp docker-compose.override.example.yml docker-compose.override.yml # 按服务器情况修改 ./scripts/docker-deploy.sh # 使用 .env 里的外部 PG/Redis ./scripts/docker-deploy.sh --full --init # 连 PostgreSQL/Redis 一起起,并初始化码表 ``` -镜像构建默认使用国内 pip/npm/apt 源;`PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR` -可在 `.env` 或命令行覆盖。详细的镜像拉取加速与挂载说明见 `docker/README.md`。 +`.env` 只放应用运行配置;镜像、构建源、端口、宿主机挂载路径统一放 +`docker-compose.yml` 与 `docker-compose.override.yml`。详细的镜像拉取加速与挂载说明见 `docker/README.md`。 ## 资源目录 媒体、固件等运行时文件统一放在项目根 `data/`,只有 `regions.json` 入库,其余内容被 `.gitignore` 忽略。 -服务器或容器部署时把该目录挂到宿主机磁盘即可;也可以用 `DATA_DIR` 指向别的位置: +裸机部署可用 `DATA_DIR` 指向别的位置;Docker 部署在 override 文件的 `volumes` 里改宿主机路径: ```bash DATA_DIR=/srv/nex_buddy/data diff --git a/scripts/docker-deploy.sh b/scripts/docker-deploy.sh index c2f527a..f304c61 100755 --- a/scripts/docker-deploy.sh +++ b/scripts/docker-deploy.sh @@ -43,6 +43,10 @@ if [ ! -f .env ]; then fi FILES=(-f docker-compose.yml) +if [ -f docker-compose.override.yml ]; then + FILES+=(-f docker-compose.override.yml) + echo ">> 使用 docker-compose.override.yml" +fi if [ "$FULL" = 1 ]; then FILES+=(-f docker-compose.full.yml) fi