# 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) ``` - 前端 ;接口文档 - 健康检查 `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=` | 扫码落地页:设备票据换会话,成功后跳个人页(不走登录守卫) | — | | `/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:` | Web 会话,value=user_id,7 天滑动 | | `dtoken::` | 设备 token 白名单,解绑即删 | | `pair:` / `pairtry:` | 配对码(10 分钟)/ 防爆破计数(5 次/分钟) | | `wlogin:` / `wlogin:dev:` | 扫码票据(5 分钟、取出即删)/ 该设备最新一张 | | `weather:` | 天气结果缓存(30 分钟) | | `cache:meta:*` | 码表/星座/运势缓存(1 小时,写操作即失效) | **安全** - 口令 bcrypt(cost 12),超 72 字节先截断;登录失败不区分"账号不存在/密码错"; - token 只存哈希,库里没有任何明文凭证; - 设备 token 形如 `:`,自带身份,解绑按前缀批量吊销; - 媒体预览允许 `?t=`(``/`