nex_buddy/docker/README.md

4.5 KiB
Raw Blame History

Docker 部署

命令统一使用 Docker Compose v2 的 docker compose(带空格)。旧版 docker-compose 不支持本项目的顶层 name 与 depends_on.condition 写法,请先安装 Compose v2 插件。

文件

文件 用途
docker/Dockerfile.api FastAPI 镜像(多阶段构建)
docker/Dockerfile.web 前端构建 + Nginx 镜像
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

配置放哪里

  • .env:只放应用运行配置,例如 DATABASE_URL、REDIS_URL、和风 Key、会话 TTL。
  • docker-compose.yml:镜像构建、基础镜像、端口映射、数据挂载。
  • docker-compose.full.yml:额外启动 PostgreSQL + Redis,与主文件组合使用。

国内下载加速

构建参数默认已经改成国内源,可直接改 docker-compose.yml,或在命令行覆盖:

参数 默认值 用途
PIP_INDEX_URL https://pypi.tuna.tsinghua.edu.cn/simple pip 包
APT_MIRROR mirrors.tuna.tsinghua.edu.cn Debian apt(仅构建阶段)
NPM_REGISTRY https://registry.npmmirror.com npm 包
# 临时换源构建
PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ \
APT_MIRROR=mirrors.aliyun.com \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose build

Docker 镜像本身不在这里配置;如果 docker pull 慢,在宿主机 /etc/docker/daemon.json 配镜像加速,然后重启 Docker:

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

镜像加速地址会变化,以当前可用的服务为准。

基础镜像

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:22-alpine
NGINX_IMAGE nginx:latest
PYTHON_IMAGE=python:3.12-slim \
NODE_IMAGE=node:22-alpine \
NGINX_IMAGE=nginx:latest \
docker compose build

如果本地镜像名称和默认值一致,Docker 会直接使用本地镜像;只有本地找不到时才会去 Registry 拉取。基础镜像仍然建议配置 registry-mirrors,否则首次构建或镜像更新时还是要访问外网。

数据目录

容器内固定使用 /app/data,Compose 默认把宿主机 ./data 挂进去:

volumes:
  - "${NEX_BUDDY_DATA_DIR:-./data}:/app/data"

所以把 docker-compose.yml 的挂载路径改成独立磁盘,或设置 NEX_BUDDY_DATA_DIR 即可:

services:
  api:
    volumes:
      - /srv/nex_buddy/data:/app/data

首次挂载空目录时,entrypoint 会把镜像内的 regions.json 复制进去;媒体和固件目录会自动创建。

宿主机端口由 .env 控制,容器内端口固定不变:

变量 宿主机端口 容器内端口 服务
FRONTEND_PORT 5173(示例) 80 Web / Nginx
BACKEND_PORT 8000(示例) 8000 API

只通过 Nginx 的 /api、/device 访问后端时,BACKEND_PORT 的宿主机映射可以删除; 需要直接访问接口文档或设备直连 API 时保留。

全栈数据库

--full 时建议用 shell 环境变量传 PostgreSQL 口令,不要把构建或部署参数塞回 .env:

POSTGRES_PASSWORD='强口令' ./scripts/docker-deploy.sh --full --init

数据库地址怎么写

容器里的 127.0.0.1 / localhost 永远指容器自己,不是宿主机。

数据库位置 DATABASE_URL 主机 额外配置
Compose 的 postgres 服务 postgres 用 --full 启动
宿主机上的 PostgreSQL host.docker.internal 已默认配置 extra_hosts
宿主机局域网 IP 192.168.x.x PostgreSQL 监听 0.0.0.0,放行防火墙
另一个 Docker 容器 容器名或服务名 两个容器在同一 Docker 网络

REDIS_URL 同理。宿主机上的 PostgreSQL/Redis 必须监听容器能访问的地址, 只监听 127.0.0.1 时,即使写 host.docker.internal 也会 Connection refused。