nex_buddy/README.md

211 lines
11 KiB
Markdown
Raw 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.

# nex_buddy · 服务平台
圆屏旋钮设备的服务端:账号、设备绑定、扫码登录、资料与星盘、天气、月度运势、TF 卡媒体同步、固件 OTA。
配套文档:`../01-总体设计.md`(架构与决策)、`../03-服务端开发文档.md`(数据模型/接口/流程/排查)、
`../04-Web前端开发规范.md`(页面与 UI 约定)、`../02-开发计划.md`(里程碑与待办)。
当前状态:M1–M4 完成,M5(音乐)缺副控真机联调;冒烟 `server/scripts/smoke.py` **71 项**全绿。
---
## 快速开始
```bash
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 在镜像里构建。
```bash
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`。
```bash
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` | 用户没填城市时的兜底(默认杭州) |
---
## 已知问题
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。