nex_buddy/docker/README.md

127 lines
4.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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 包 |
```bash
# 临时换源构建
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:
```json
{
"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` |
```bash
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` 挂进去:
```yaml
volumes:
- "${NEX_BUDDY_DATA_DIR:-./data}:/app/data"
```
所以把 `docker-compose.yml` 的挂载路径改成独立磁盘,或设置 `NEX_BUDDY_DATA_DIR` 即可:
```yaml
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`:
```bash
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`。