Go to file
mula.liu 96dbdaa714 设备接口:时区按用户算、图片待同步数修正、天气上游失败回落旧值
- /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 便于定位出网问题。
2026-11-13 21:32:18 +08:00
data v 0.1.2 2026-11-13 14:38:19 +08:00
docker 设备接口:时区按用户算、图片待同步数修正、天气上游失败回落旧值 2026-11-13 21:32:18 +08:00
scripts 修改了构建配置 2026-11-13 16:51:05 +08:00
server 设备接口:时区按用户算、图片待同步数修正、天气上游失败回落旧值 2026-11-13 21:32:18 +08:00
web 修改了构建配置 2026-11-13 16:51:05 +08:00
.dockerignore 修改了部署文件 2026-11-13 15:01:11 +08:00
.env.example 修改了构建配置 2026-11-13 16:54:51 +08:00
.gitignore 修改了构建配置 2026-11-13 16:40:28 +08:00
README.md 修改了构建配置 2026-11-13 16:54:51 +08:00
docker-compose.full.yml 修改了构建配置 2026-11-13 16:40:28 +08:00
docker-compose.yml 设备接口:时区按用户算、图片待同步数修正、天气上游失败回落旧值 2026-11-13 21:32:18 +08:00
requirements.txt v 0.1.2 2026-11-13 14:38:19 +08:00

README.md

nex_buddy · 服务平台

圆屏旋钮设备的服务端:账号、设备绑定、扫码登录、资料与星盘、天气、月度运势、TF 卡媒体同步、固件 OTA。 配套文档:../01-总体设计.md(架构与决策)、../03-服务端开发文档.md(数据模型/接口/流程/排查)、 ../04-Web前端开发规范.md(页面与 UI 约定)、../02-开发计划.md(里程碑与待办)。

当前状态:M1–M4 完成,M5(音乐)缺副控真机联调;冒烟 server/scripts/smoke.py 71 项全绿。


快速开始

cd 01-开发工作区/服务平台/nex_buddy
cp .env.example .env          # 首次:填数据库/Redis/和风凭据
./scripts/dev.sh              # 后端:建 venv → alembic upgrade head → uvicorn :8000
# 媒体、固件等运行时资源统一放在根目录 data/(可用 DATA_DIR 覆盖)

# 首次初始化:码表(3442 条行政区划 + 12 星座)、月度运势、管理员
cd server
../.venv/bin/python scripts/seed_catalog.py
../.venv/bin/python scripts/seed_fortunes.py
../.venv/bin/python scripts/create_admin.py --account admin@nexbuddy.com --password 'NexBuddy2026'

cd ../web && npm install && npm run dev   # 前端 5173,/api 与 /device 代理到 8000(端口都在根 .env)
  • 前端 http://127.0.0.1:5173;接口文档 http://127.0.0.1:8000/docs
  • 健康检查 GET /healthz → {ok, db, redis, weather_ready}(设备配网页的「测试连通」就是打它)
  • 端到端自测:cd server && ../.venv/bin/python scripts/smoke.py 会创建 smoke*@test.local 用户与 SMOKE* 设备,跑完按 ../03-服务端开发文档.md §10.3 清理

管理员 admin@nexbuddy.com / NexBuddy2026(create_admin.py 生成,可重跑改口令)。 设备默认服务端地址写在固件 src/config/AppConfig.h 的 DEFAULT_SERVER_URL,真机以 NVS 里的值为准。


服务器部署

脚本都在 scripts/,项目路径以 /opt/nex_buddy 为例:

直接部署需要:Python 3.12+、Node.js 18+、PostgreSQL、Redis、Nginx(数据库/Redis 也可用现成的远程实例)。 Docker 部署只需要 Docker + Docker Compose,Python/Node 在镜像里构建。

cd /opt/nex_buddy
cp .env.example .env
# 编辑 .env:APP_ENV=prod;DATABASE_URL / REDIS_URL 改成服务器地址;
# 同域部署不用配 CORS_ORIGINS;如需把资源放到宿主机其他磁盘:
# DATA_DIR=/srv/nex_buddy/data

./scripts/deploy.sh --init --no-restart   # venv + 依赖 + 迁移 + 码表/运势 + 构建 web/dist

# 首次部署建管理员(可重跑改口令)
cd server && ../.venv/bin/python scripts/create_admin.py \
  --account admin@nexbuddy.com --password '换成强口令'
cd ..

sudo cp scripts/nex-buddy.service /etc/systemd/system/nex-buddy.service
sudo vim /etc/systemd/system/nex-buddy.service   # 改 User / WorkingDirectory
sudo chown -R www-data:www-data data             # 运行用户需要写媒体/固件目录
sudo systemctl daemon-reload
sudo systemctl enable --now nex-buddy

sudo cp scripts/nginx-nex-buddy.conf /etc/nginx/sites-available/nex-buddy
sudo vim /etc/nginx/sites-available/nex-buddy    # 改 server_name / root
sudo ln -s /etc/nginx/sites-available/nex-buddy /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
  • scripts/deploy.sh:默认安装依赖、执行迁移、构建前端;检测到 nex-buddy.service 时会自动重启并做 /healthz 健康检查。 可选 --init / --no-web / --no-migrate / --skip-install / --no-restart。
  • scripts/start.sh:生产启动入口(uvicorn --workers,供 systemd 调用),不负责迁移和构建。
  • scripts/dev.sh:开发启动入口(带 --reload)。
  • Nginx 采用同域反代:/ 出静态文件,/api/、/device/、/healthz 转给后端,因此浏览器不需要 CORS。
  • 运行时资源只有一个根:data/。部署时整体挂载或指向宿主机磁盘即可: DATA_DIR=/srv/nex_buddy/data,或容器里把宿主机目录挂到 /app/data。

Docker 部署

不想在宿主机装 Python/Node 时用这套。默认使用 .env 里的外部 PostgreSQL/Redis; 需要连数据库一起起时加 --full。

cp .env.example .env
# APP_ENV=prod;外部 DB/Redis 填 DATABASE_URL / REDIS_URL

./scripts/docker-deploy.sh                # 已有 PG/Redis
./scripts/docker-deploy.sh --full --init  # 连 PG/Redis 一起起,并初始化码表

# 首次建管理员
docker compose exec api python server/scripts/create_admin.py \
  --account admin@nexbuddy.com --password '强口令'
  • data/ 会挂载到容器 /app/data,媒体、固件、码表都在这里。
  • .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。
  • --full 时用环境变量传口令:POSTGRES_PASSWORD='强口令' ./scripts/docker-deploy.sh --full --init。

目录

nex_buddy/
├── .env / .env.example      配置(.env 不入库)
├── .dockerignore
├── docker-compose.yml       API + Web(外部 DB/Redis)
├── docker-compose.full.yml  全栈:额外启动 PostgreSQL + Redis
├── docker/                  镜像、Nginx、entrypoint 与 Docker 说明
├── scripts/                 启动 / 部署 / systemd / Nginx 脚本
├── data/                    运行时资源:regions.json + media/ + firmware/(媒体与固件不入库)
├── server/
│   ├── migrations/          Alembic 迁移(7 个版本,head 464bf9d382f4)
│   ├── scripts/             smoke.py(71 项) / smoke_firmware.py / smoke_weblogin.py / seed_*.py / create_admin.py
│   └── app/
│       ├── main.py          路由挂载 + /healthz + 兜底异常处理
│       ├── core/            config(.env 映射)、security(bcrypt/token/配对码)
│       ├── db/              async engine 与 session
│       ├── models/          user / device / firmware / media / region / zodiac / fortune / setting
│       ├── schemas/         auth / catalog / firmware
│       ├── api/             auth / devices / media / meta / admin / device_v1 / deps
│       └── services/        astro / catalog / fortune / weather / firmware / media / redis_store
└── web/                     React + antd(Vite)
    └── src/                 api.ts / theme.tsx / i18n.ts / styles.css / components / pages

页面

路由 内容 截图
/login 登录 / 注册(同一张卡,Segmented 切换) docs/shots/web-login.png
/qr?t=<code> 扫码落地页:设备票据换会话,成功后跳个人页(不走登录守卫) —
/bind 绑定页,支持 ?code=&did= 预填 docs/shots/web-bind.png
/ 账号 → 我的设备 → TF 卡文件 / 个人资料(昵称·常住城市·时区)+ 出生信息与星盘(含本月运势) docs/shots/web-home.png
/admin 六个页签:用户与设备、城市码表、星座码表、月度运势、固件管理、平台设置 docs/shots/admin-*.png、admin-users-mobile.png

细节与 UI 规则见 ../04-Web前端开发规范.md;截图清单与四态(浅/深/英/移动)命名也在那里。


关键设计

Redis 键(db 9,完整表见 03 §8)

键 用途
sess:<sha256(token)> Web 会话,value=user_id,7 天滑动
dtoken:<device_id>:<sha256(secret)> 设备 token 白名单,解绑即删
pair:<code> / pairtry:<code> 配对码(10 分钟)/ 防爆破计数(5 次/分钟)
wlogin:<code> / wlogin:dev:<device_id> 扫码票据(5 分钟、取出即删)/ 该设备最新一张
weather:<city> 天气结果缓存(30 分钟)
cache:meta:* 码表/星座/运势缓存(1 小时,写操作即失效)

安全

  • 口令 bcrypt(cost 12),超 72 字节先截断;登录失败不区分"账号不存在/密码错";
  • token 只存哈希,库里没有任何明文凭证;
  • 设备 token 形如 <device_id>:<secret>,自带身份,解绑按前缀批量吊销;
  • 媒体预览允许 ?t=<token>(<img>/<audio> 带不了头),仅在 CurrentUserAny 依赖里生效。

天气(和风)

  • 配置优先级:平台设置(库)> .env,直读库不缓存;只有查询结果进 Redis;
  • Key 两种形态:32 位 Key 走 X-QW-Api-Key,JWT 走 Authorization: Bearer;
  • Host 是账号专属域名(xxx.re.qweatherapi.com),不能由 Key 推导;项目 ID(HE…)不是 Key;
  • 缺 Host/Key → 503 带指引;上游异常 → 502,不吞成 500。

码表 / 时区 / 星盘

  • 地区即 GB/T 2260:省补 0000、地级市补 00、区县原样,共 3442 条;直辖市不重复一层(changeOnSelect);
  • 用户只存 code,展示名由服务端反查落一份;管理端改名只影响下次读取;
  • users.timezone 空则跟随常住地,再兜底 Asia/Shanghai;只影响"今天/本月",星盘永远用出生地时区;
  • 星盘用 pyswisseph 的 Moshier 解析式(无星历文件依赖),保存资料时算好落库;不填出生时间按当日 12:00 近似。

运势

  • fortunes 两层:scope='month' 通用模板(每年复用)、scope='ym' 指定年月;取值顺序 ym → month → 内置模板;
  • 中英各一份,英文缺失回退中文;"本月"按居住时区判定,跨年不串月。

配置项

变量 说明
DATABASE_URL postgresql+asyncpg://用户:口令@主机:5432/nex_buddy
REDIS_URL redis://主机:6379/9(db 9 是项目专属库)
QWEATHER_KEY / QWEATHER_HOST 和风凭据;也可在管理端「平台设置」里改(库里优先)
WEB_BASE_URL 二维码里 Web 地址的覆盖值;空则按设备请求 Host 推导(同域部署不用配)
DATA_DIR 运行时资源根目录,默认项目根 data/;服务器/容器部署可指向宿主机挂载点
BACKEND_PORT / FRONTEND_PORT 端口(默认 8000 / 5173):开发时是监听端口,Docker 部署时是宿主机映射端口;容器内固定为 8000 / 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 用户没填城市时的兜底(默认杭州)

已知问题

  1. Redis 快照写盘失败(rdb_last_bgsave_status=err,dir=/data):已临时 CONFIG SET stop-writes-on-bgsave-error no(重启失效)。 业务数据在 PG,丢快照只影响登录态;根治要在服务器查 df -h /data 与 Redis 日志。
  2. 开发机 IP 用 DHCP:设备 net.server 与截图脚本里的地址会变,改配置以设备 NVS/命令行参数为准。
  3. 后端偶发事件循环卡死(端口在听但请求超时):lsof -i :8000 找 PID → kill -9 → 重新 ./scripts/dev.sh;排查见 03 §10。