diff --git a/.env.example b/.env.example index 4fa37e4..876f5e7 100644 --- a/.env.example +++ b/.env.example @@ -3,9 +3,10 @@ APP_ENV=dev APP_VERSION=0.1.0 -# ---- 端口(开发期) ---- -# scripts/dev.sh 起后端、vite 起前端都读这里。localhost 的 CORS 源会自动跟随 -# FRONTEND_PORT;手机/局域网访问走 Vite 代理,不需要额外配置 CORS。 +# ---- 端口 ---- +# 开发:scripts/dev.sh 监听 BACKEND_PORT,Vite 监听 FRONTEND_PORT。 +# Docker:这两个值是宿主机映射端口,容器内仍是 8100 / 80。 +# localhost 的 CORS 源会自动跟随 FRONTEND_PORT;同域部署不需要额外配置 CORS。 BACKEND_PORT=8100 FRONTEND_PORT=5174 diff --git a/.gitignore b/.gitignore index a853fa1..f127dc3 100644 --- a/.gitignore +++ b/.gitignore @@ -18,7 +18,6 @@ build/ .env .env.* !.env.example -docker-compose.override.yml # ---- 运行时资源 ---- # data/ 下是用户上传与固件包,默认不入库; diff --git a/README.md b/README.md index 50c2188..9172df3 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,6 @@ sudo nginx -t && sudo systemctl reload nginx cp .env.example .env # APP_ENV=prod;外部 DB/Redis 填 DATABASE_URL / REDIS_URL -# 服务器差异项(基础镜像、构建源、端口、宿主机挂载路径)放这里 -cp docker-compose.override.example.yml docker-compose.override.yml - ./scripts/docker-deploy.sh # 已有 PG/Redis ./scripts/docker-deploy.sh --full --init # 连 PG/Redis 一起起,并初始化码表 @@ -97,8 +94,8 @@ docker compose exec api python server/scripts/create_admin.py \ ``` - `data/` 会挂载到容器 `/app/data`,媒体、固件、码表都在这里。 -- `.env` 只放应用运行配置;构建源、端口、挂载路径都放 `docker-compose.override.yml`。 -- 构建阶段 pip / npm / apt 默认走国内源,可在 override 文件里覆盖; +- `.env` 只放应用运行配置;构建源、端口、挂载路径直接改 `docker-compose.yml`。 +- 构建阶段 pip / npm / apt 默认走国内源,可在 `docker-compose.yml` 里修改; `docker pull` 的镜像加速见 `docker/README.md`。 - Dockerfile 不再使用 `# syntax=docker/dockerfile:1`;`PYTHON_IMAGE` / `NODE_IMAGE` / `NGINX_IMAGE` 可指向服务器本地已有镜像或私有仓库,避免额外访问 Docker Hub。 @@ -113,8 +110,7 @@ nex_buddy/ ├── .env / .env.example 配置(.env 不入库) ├── .dockerignore ├── docker-compose.yml API + Web(外部 DB/Redis) -├── docker-compose.full.yml 可选:同时启动 PostgreSQL + Redis -├── docker-compose.override.example.yml 服务器差异项模板(基础镜像/源/端口/挂载) +├── docker-compose.full.yml 全栈:额外启动 PostgreSQL + Redis ├── docker/ 镜像、Nginx、entrypoint 与 Docker 说明 ├── scripts/ 启动 / 部署 / systemd / Nginx 脚本 ├── data/ 运行时资源:regions.json + media/ + firmware/(媒体与固件不入库) @@ -199,7 +195,7 @@ nex_buddy/ | `QWEATHER_KEY` / `QWEATHER_HOST` | 和风凭据;也可在管理端「平台设置」里改(库里优先) | | `WEB_BASE_URL` | 二维码里 Web 地址的**覆盖值**;空则按设备请求 Host 推导(同域部署不用配) | | `DATA_DIR` | 运行时资源根目录,默认项目根 `data/`;服务器/容器部署可指向宿主机挂载点 | -| `BACKEND_PORT` / `FRONTEND_PORT` | 开发期端口(默认 8100 / 5174):`scripts/dev.sh` 与 `vite.config.ts` 都读它,改一处即可;localhost 的 CORS 源自动跟随 | +| `BACKEND_PORT` / `FRONTEND_PORT` | 端口(默认 8100 / 5174):开发时是监听端口,Docker 部署时是宿主机映射端口;容器内固定为 8100 / 80。localhost 的 CORS 源自动跟随 | | `CORS_ORIGINS` | **一般不用配**:同域部署不需要;仅 Web 与 API 分离域时设置,如 `https://app.example.com`。配了 `WEB_BASE_URL` 时其源会自动放行 | | `SESSION_TTL_SECONDS` / `PAIR_CODE_TTL_SECONDS` / `WEB_LOGIN_TTL_SECONDS` | 会话 7 天 / 配对码 10 分钟 / 扫码票据 5 分钟 | | `DEFAULT_CITY` | 用户没填城市时的兜底(默认杭州) | diff --git a/docker-compose.full.yml b/docker-compose.full.yml index 42595c1..9f0f2b4 100644 --- a/docker-compose.full.yml +++ b/docker-compose.full.yml @@ -1,5 +1,6 @@ -# 可选覆盖文件:把 PostgreSQL / Redis 也交给 Compose 管理。 +# 全栈部署:与 docker-compose.yml 组合使用,额外启动 PostgreSQL / Redis。 # 用法:./scripts/docker-deploy.sh --full +# 手动启动:docker compose -f docker-compose.yml -f docker-compose.full.yml up -d services: postgres: diff --git a/docker-compose.override.example.yml b/docker-compose.override.example.yml deleted file mode 100644 index 810bfd6..0000000 --- a/docker-compose.override.example.yml +++ /dev/null @@ -1,32 +0,0 @@ -# 复制为 docker-compose.override.yml 后按需修改;该文件不入库。 -# -# cp docker-compose.override.example.yml docker-compose.override.yml -# -# docker-deploy.sh 与 docker compose 会自动带上这个覆盖文件。 - -services: - api: - # host.docker.internal 已在 docker-compose.yml 里默认配置; - # 数据库在宿主机时,把 .env 的 DATABASE_URL / REDIS_URL 改成 host.docker.internal 即可。 - 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:22-alpine - NGINX_IMAGE: nginx:latest - 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 99b8d43..10c5887 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,8 +2,7 @@ name: nex-buddy services: api: - # 构建源与基础镜像默认值都在这里;服务器差异项建议写到 - # docker-compose.override.yml(可从 docker-compose.override.example.yml 复制)。 + # 构建源与基础镜像默认值都在这里;服务器有差异时直接改本文件。 build: context: . dockerfile: docker/Dockerfile.api @@ -22,13 +21,16 @@ services: environment: # 容器内固定使用 /app/data,宿主机路径由下面的 volumes 决定 DATA_DIR: /app/data + # 容器内端口固定;宿主机映射端口由 .env 的 BACKEND_PORT 决定 + BACKEND_PORT: "8100" FORWARDED_ALLOW_IPS: "*" WEB_CONCURRENCY: "${WEB_CONCURRENCY:-2}" volumes: - # 默认挂载项目根 data/;要换宿主机磁盘就改这里或写 override 文件 + # 默认挂载项目根 data/;要换宿主机磁盘就改这里,或用 NEX_BUDDY_DATA_DIR 指定 - "${NEX_BUDDY_DATA_DIR:-./data}:/app/data" - expose: - - "8100" + ports: + # 宿主机端口由 .env 的 BACKEND_PORT 决定;容器内始终是 8100 + - "${BACKEND_PORT:-8000}:8000" restart: unless-stopped healthcheck: test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8100/healthz', timeout=3)"] @@ -47,8 +49,8 @@ services: NGINX_IMAGE: "${NGINX_IMAGE:-nginx:latest}" image: nex-buddy-web:latest ports: - # 对外端口默认 80;要换就改这里或写 override 文件 - - "${HTTP_PORT:-80}:80" + # 宿主机端口由 .env 的 FRONTEND_PORT 决定;容器内始终是 80 + - "${FRONTEND_PORT:-5173}:5173" depends_on: api: condition: service_healthy diff --git a/docker/README.md b/docker/README.md index 3013b57..658cfeb 100644 --- a/docker/README.md +++ b/docker/README.md @@ -12,22 +12,17 @@ | `docker/nginx.conf` | 容器内 Nginx:静态文件 + `/api`、`/device` 反代 | | `docker/api-entrypoint.sh` | 启动前创建数据目录、补 `regions.json`、执行迁移 | | `docker-compose.yml` | API + Web;数据库/Redis 使用 `.env` 中的外部实例 | -| `docker-compose.full.yml` | 可选覆盖:同时启动 PostgreSQL + Redis | -| `docker-compose.override.example.yml` | 服务器差异项模板:基础镜像、构建源、端口、挂载路径 | +| `docker-compose.full.yml` | 全栈部署:额外启动 PostgreSQL + Redis | ## 配置放哪里 - `.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 -``` +- `docker-compose.yml`:镜像构建、基础镜像、端口映射、数据挂载。 +- `docker-compose.full.yml`:额外启动 PostgreSQL + Redis,与主文件组合使用。 ## 国内下载加速 -构建参数默认已经改成国内源,可在 `docker-compose.override.yml` 或命令行覆盖: +构建参数默认已经改成国内源,可直接改 `docker-compose.yml`,或在命令行覆盖: | 参数 | 默认值 | 用途 | |---|---|---| @@ -87,7 +82,7 @@ volumes: - "${NEX_BUDDY_DATA_DIR:-./data}:/app/data" ``` -所以把 `docker-compose.override.yml` 的挂载路径改成独立磁盘即可: +所以把 `docker-compose.yml` 的挂载路径改成独立磁盘,或设置 `NEX_BUDDY_DATA_DIR` 即可: ```yaml services: @@ -98,11 +93,15 @@ services: 首次挂载空目录时,entrypoint 会把镜像内的 `regions.json` 复制进去;媒体和固件目录会自动创建。 -Web 对外端口默认 80,可在 `docker-compose.yml` 的 `web.ports` 修改,或运行时指定: +宿主机端口由 `.env` 控制,容器内端口固定不变: -```bash -HTTP_PORT=8080 ./scripts/docker-deploy.sh -``` +| 变量 | 宿主机端口 | 容器内端口 | 服务 | +|---|---|---|---| +| `FRONTEND_PORT` | `5174`(示例) | `80` | Web / Nginx | +| `BACKEND_PORT` | `8100`(示例) | `8100` | API | + +只通过 Nginx 的 `/api`、`/device` 访问后端时,`BACKEND_PORT` 的宿主机映射可以删除; +需要直接访问接口文档或设备直连 API 时保留。 ## 全栈数据库 diff --git a/scripts/README.md b/scripts/README.md index e2cc295..fc0222d 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -42,18 +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 一起起,并初始化码表 ``` `.env` 只放应用运行配置;镜像、构建源、端口、宿主机挂载路径统一放 -`docker-compose.yml` 与 `docker-compose.override.yml`。详细的镜像拉取加速与挂载说明见 `docker/README.md`。 +`docker-compose.yml`;需要数据库/Redis 同机启动时再叠加 `docker-compose.full.yml`。 +详细的镜像拉取加速与挂载说明见 `docker/README.md`。 ## 资源目录 媒体、固件等运行时文件统一放在项目根 `data/`,只有 `regions.json` 入库,其余内容被 `.gitignore` 忽略。 -裸机部署可用 `DATA_DIR` 指向别的位置;Docker 部署在 override 文件的 `volumes` 里改宿主机路径: +裸机部署可用 `DATA_DIR` 指向别的位置;Docker 部署在 `docker-compose.yml` 的 `volumes` 里改宿主机路径: ```bash DATA_DIR=/srv/nex_buddy/data diff --git a/scripts/docker-deploy.sh b/scripts/docker-deploy.sh index f304c61..c2f527a 100755 --- a/scripts/docker-deploy.sh +++ b/scripts/docker-deploy.sh @@ -43,10 +43,6 @@ 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