- /device/v1/ping:ts 按用户居住时区返回(原来 astimezone() 拿的是容器 UTC, 设备照抄 TZ 屏幕上差 8 小时),并给 tz / tz_offset_min / utc。 - UserOut 增加 tz_offset_min(设备没有 tzdata,光有 IANA 名换算不了)。 - /device/v1/media/pending:pending_pic 原来按 kind == "pic" 统计, 而实际取值是 image,所以图片数永远是 0 → 相册弹窗只报总口径。 - 和风上游连不上时,回 24h 内的最后一次成功结果并标 stale, 比让设备显示"暂无数据"有用;错误信息带上 host 便于定位出网问题。 |
||
|---|---|---|
| .. | ||
| Dockerfile.api | ||
| Dockerfile.web | ||
| README.md | ||
| api-entrypoint.sh | ||
| nginx.conf | ||
README.md
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。