11 KiB
11 KiB
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 是项目专属库) |
和风 API Key / API Host |
只在管理端「平台设置」保存到数据库,运行时不读 .env |
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 |
用户没填城市时的兜底(默认杭州) |
已知问题
- Redis 快照写盘失败(
rdb_last_bgsave_status=err,dir=/data):已临时CONFIG SET stop-writes-on-bgsave-error no(重启失效)。 业务数据在 PG,丢快照只影响登录态;根治要在服务器查df -h /data与 Redis 日志。 - 开发机 IP 用 DHCP:设备
net.server与截图脚本里的地址会变,改配置以设备 NVS/命令行参数为准。 - 后端偶发事件循环卡死(端口在听但请求超时):
lsof -i :8000找 PID →kill -9→ 重新./scripts/dev.sh;排查见03§10。