211 lines
11 KiB
Markdown
211 lines
11 KiB
Markdown
# 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。
|