From e253c9608a39ca7316958ef0e1ec09cd85c7b353 Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Fri, 13 Nov 2026 14:38:19 +0800 Subject: [PATCH] v 0.1.2 --- .dockerignore | 30 + .env.example | 52 + .gitignore | 29 + README.md | 208 + data/regions.json | 27538 ++++++++++++++++ docker-compose.full.yml | 44 + docker-compose.yml | 43 + docker/Dockerfile.api | 52 + docker/Dockerfile.web | 22 + docker/README.md | 58 + docker/api-entrypoint.sh | 25 + docker/nginx.conf | 45 + requirements.txt | 13 + scripts/README.md | 70 + scripts/deploy.sh | 135 + scripts/dev.sh | 23 + scripts/docker-deploy.sh | 65 + scripts/nex-buddy.service | 26 + scripts/nginx-nex-buddy.conf | 44 + scripts/start.sh | 25 + server/alembic.ini | 42 + server/app/__init__.py | 0 server/app/api/__init__.py | 0 server/app/api/admin.py | 661 + server/app/api/auth.py | 199 + server/app/api/deps.py | 105 + server/app/api/device_v1.py | 517 + server/app/api/devices.py | 129 + server/app/api/media.py | 170 + server/app/api/meta.py | 109 + server/app/core/__init__.py | 0 server/app/core/config.py | 106 + server/app/core/security.py | 56 + server/app/db/__init__.py | 0 server/app/db/session.py | 43 + server/app/main.py | 99 + server/app/models/__init__.py | 22 + server/app/models/device.py | 61 + server/app/models/firmware.py | 57 + server/app/models/fortune.py | 39 + server/app/models/media.py | 73 + server/app/models/region.py | 34 + server/app/models/setting.py | 23 + server/app/models/user.py | 66 + server/app/models/zodiac.py | 37 + server/app/schemas/__init__.py | 0 server/app/schemas/auth.py | 143 + server/app/schemas/catalog.py | 116 + server/app/schemas/firmware.py | 86 + server/app/services/__init__.py | 0 server/app/services/astro.py | 81 + server/app/services/catalog.py | 135 + server/app/services/firmware.py | 193 + server/app/services/fortune.py | 99 + server/app/services/media.py | 282 + server/app/services/redis_store.py | 188 + server/app/services/weather.py | 140 + server/migrations/env.py | 62 + server/migrations/script.py.mako | 27 + ...7c3af368f8_media_files_and_device_media.py | 59 + ...54651241d66_init_users_devices_settings.py | 75 + ...eef1366efd_regions_zodiac_profile_astro.py | 80 + .../3dd02ef90e3c_device_media_sync_cursor.py | 34 + .../versions/464bf9d382f4_media_file_cover.py | 33 + ...eae4_firmwares_and_device_upgrade_state.py | 74 + ...20b1fc56c_user_timezone_zodiac_fortunes.py | 48 + server/scripts/create_admin.py | 60 + server/scripts/seed_catalog.py | 98 + server/scripts/seed_fortunes.py | 102 + server/scripts/smoke.py | 345 + server/scripts/smoke_firmware.py | 172 + server/scripts/smoke_weblogin.py | 94 + web/.gitignore | 7 + web/index.html | 30 + web/package-lock.json | 3019 ++ web/package.json | 26 + web/src/App.tsx | 52 + web/src/api.ts | 397 + web/src/components/LangSwitch.tsx | 32 + web/src/components/MediaCard.tsx | 323 + web/src/components/ThemeSwitch.tsx | 23 + web/src/components/TopBar.tsx | 94 + web/src/components/icons.tsx | 216 + web/src/i18n.ts | 43 + web/src/locales/en.ts | 305 + web/src/locales/zh.ts | 305 + web/src/main.tsx | 52 + web/src/pages/Admin.tsx | 1044 + web/src/pages/AdminFirmware.tsx | 567 + web/src/pages/Bind.tsx | 110 + web/src/pages/Home.tsx | 519 + web/src/pages/Login.tsx | 109 + web/src/pages/QrLogin.tsx | 96 + web/src/styles.css | 920 + web/src/theme.tsx | 142 + web/tsconfig.json | 19 + web/vite.config.ts | 51 + 97 files changed, 42522 insertions(+) create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 README.md create mode 100644 data/regions.json create mode 100644 docker-compose.full.yml create mode 100644 docker-compose.yml create mode 100644 docker/Dockerfile.api create mode 100644 docker/Dockerfile.web create mode 100644 docker/README.md create mode 100755 docker/api-entrypoint.sh create mode 100644 docker/nginx.conf create mode 100644 requirements.txt create mode 100644 scripts/README.md create mode 100755 scripts/deploy.sh create mode 100755 scripts/dev.sh create mode 100755 scripts/docker-deploy.sh create mode 100644 scripts/nex-buddy.service create mode 100644 scripts/nginx-nex-buddy.conf create mode 100755 scripts/start.sh create mode 100644 server/alembic.ini create mode 100644 server/app/__init__.py create mode 100644 server/app/api/__init__.py create mode 100644 server/app/api/admin.py create mode 100644 server/app/api/auth.py create mode 100644 server/app/api/deps.py create mode 100644 server/app/api/device_v1.py create mode 100644 server/app/api/devices.py create mode 100644 server/app/api/media.py create mode 100644 server/app/api/meta.py create mode 100644 server/app/core/__init__.py create mode 100644 server/app/core/config.py create mode 100644 server/app/core/security.py create mode 100644 server/app/db/__init__.py create mode 100644 server/app/db/session.py create mode 100644 server/app/main.py create mode 100644 server/app/models/__init__.py create mode 100644 server/app/models/device.py create mode 100644 server/app/models/firmware.py create mode 100644 server/app/models/fortune.py create mode 100644 server/app/models/media.py create mode 100644 server/app/models/region.py create mode 100644 server/app/models/setting.py create mode 100644 server/app/models/user.py create mode 100644 server/app/models/zodiac.py create mode 100644 server/app/schemas/__init__.py create mode 100644 server/app/schemas/auth.py create mode 100644 server/app/schemas/catalog.py create mode 100644 server/app/schemas/firmware.py create mode 100644 server/app/services/__init__.py create mode 100644 server/app/services/astro.py create mode 100644 server/app/services/catalog.py create mode 100644 server/app/services/firmware.py create mode 100644 server/app/services/fortune.py create mode 100644 server/app/services/media.py create mode 100644 server/app/services/redis_store.py create mode 100644 server/app/services/weather.py create mode 100644 server/migrations/env.py create mode 100644 server/migrations/script.py.mako create mode 100644 server/migrations/versions/067c3af368f8_media_files_and_device_media.py create mode 100644 server/migrations/versions/254651241d66_init_users_devices_settings.py create mode 100644 server/migrations/versions/30eef1366efd_regions_zodiac_profile_astro.py create mode 100644 server/migrations/versions/3dd02ef90e3c_device_media_sync_cursor.py create mode 100644 server/migrations/versions/464bf9d382f4_media_file_cover.py create mode 100644 server/migrations/versions/602dc965eae4_firmwares_and_device_upgrade_state.py create mode 100644 server/migrations/versions/d8b20b1fc56c_user_timezone_zodiac_fortunes.py create mode 100644 server/scripts/create_admin.py create mode 100644 server/scripts/seed_catalog.py create mode 100644 server/scripts/seed_fortunes.py create mode 100644 server/scripts/smoke.py create mode 100644 server/scripts/smoke_firmware.py create mode 100644 server/scripts/smoke_weblogin.py create mode 100644 web/.gitignore create mode 100644 web/index.html create mode 100644 web/package-lock.json create mode 100644 web/package.json create mode 100644 web/src/App.tsx create mode 100644 web/src/api.ts create mode 100644 web/src/components/LangSwitch.tsx create mode 100644 web/src/components/MediaCard.tsx create mode 100644 web/src/components/ThemeSwitch.tsx create mode 100644 web/src/components/TopBar.tsx create mode 100644 web/src/components/icons.tsx create mode 100644 web/src/i18n.ts create mode 100644 web/src/locales/en.ts create mode 100644 web/src/locales/zh.ts create mode 100644 web/src/main.tsx create mode 100644 web/src/pages/Admin.tsx create mode 100644 web/src/pages/AdminFirmware.tsx create mode 100644 web/src/pages/Bind.tsx create mode 100644 web/src/pages/Home.tsx create mode 100644 web/src/pages/Login.tsx create mode 100644 web/src/pages/QrLogin.tsx create mode 100644 web/src/styles.css create mode 100644 web/src/theme.tsx create mode 100644 web/tsconfig.json create mode 100644 web/vite.config.ts diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..2a6ce64 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,30 @@ +# 版本控制 / 本地环境 +.git +.gitignore +.venv +.env +.env.* +!.env.example + +# Python 缓存 +**/__pycache__ +*.py[cod] +.pytest_cache +.ruff_cache + +# 前端本地依赖与产物 +web/node_modules +web/dist +web/.vite +web/tsconfig.tsbuildinfo + +# 运行时数据:只保留码表种子,媒体/固件走挂载卷 +data/* +!data/regions.json + +# 文档与截图不需要进镜像 +docs +README.md + +# 系统文件 +.DS_Store diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..c8acc47 --- /dev/null +++ b/.env.example @@ -0,0 +1,52 @@ +# ---- 运行环境 ---- +# 全部配置走环境变量/.env,不写进代码仓库(见 01-总体设计.md 第 8 节) +APP_ENV=dev +APP_VERSION=0.1.0 + +# ---- 端口(开发期) ---- +# scripts/dev.sh 起后端、vite 起前端都读这里。localhost 的 CORS 源会自动跟随 +# FRONTEND_PORT;手机/局域网访问走 Vite 代理,不需要额外配置 CORS。 +BACKEND_PORT=8100 +FRONTEND_PORT=5174 + +# ---- 数据库 ---- +DATABASE_URL=postgresql+asyncpg://postgres:sagacity@192.168.124.203:5432/nex_buddy + +# ---- 缓存 ---- +REDIS_URL=redis://192.168.124.203:6379/9 + +# ---- 和风天气 ---- +# Key 直接可用;Host 是账号专属的,登录控制台 → 设置 复制(形如 abc1234xyz.re.qweatherapi.com) +# 旧的 devapi/api.qweather.com 已返回 403 Invalid Host +QWEATHER_KEY=HE2204271924421425 +QWEATHER_HOST= + +# ---- 业务参数 ---- +SESSION_TTL_SECONDS=604800 +PAIR_CODE_TTL_SECONDS=600 +WEATHER_CACHE_SECONDS=1800 +DEFAULT_CITY=杭州 + +# ---- 资源目录 ---- +# 默认是项目根 data/;服务器/容器部署可指向宿主机挂载点 +# DATA_DIR=/srv/nex_buddy/data + +# ---- Docker 部署(可选) ---- +# 宿主机资源目录(Compose 挂载到容器 /app/data),默认 ./data +# NEX_BUDDY_DATA_DIR=/srv/nex_buddy/data +# Web 对外端口,默认 80 +# HTTP_PORT=80 +# 仅 docker-deploy.sh --full 使用;请务必改掉默认口令 +# POSTGRES_DB=nex_buddy +# POSTGRES_USER=nex_buddy +# POSTGRES_PASSWORD=change-me +# 构建加速(默认已用国内源,可覆盖) +# PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple +# APT_MIRROR=mirrors.tuna.tsinghua.edu.cn +# NPM_REGISTRY=https://registry.npmmirror.com + +# ---- CORS(一般不用配) ---- +# Web 与 API 同域部署(Nginx 反代 / 已配 WEB_BASE_URL)时不需要 CORS, +# 保持不设置即可。只有 Web 与 API 确实不同域时才需要: +# CORS_ORIGINS=https://app.example.com +# 注意写完整源(协议 + 域名 + 端口),不要用 *。 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f127dc3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,29 @@ +# ---- Python ---- +.venv/ +__pycache__/ +*.py[cod] +.pytest_cache/ +.ruff_cache/ +*.egg-info/ + +# ---- Node / 前端构建产物 ---- +web/node_modules/ +web/dist/ +web/.vite/ +web/*.local +dist/ +build/ + +# ---- 配置与密钥 ---- +.env +.env.* +!.env.example + +# ---- 运行时资源 ---- +# data/ 下是用户上传与固件包,默认不入库; +# 部署时可整体挂载到宿主机磁盘(DATA_DIR 可覆盖默认路径)。 +/data/* +!/data/regions.json + +# ---- 系统 / 编辑器 ---- +.DS_Store diff --git a/README.md b/README.md new file mode 100644 index 0000000..f5bf511 --- /dev/null +++ b/README.md @@ -0,0 +1,208 @@ +# 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 :8100 +# 媒体、固件等运行时资源统一放在根目录 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 # 前端 5174,/api 与 /device 代理到 8100(端口都在根 .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 +# 资源目录默认 ./data,也可 NEX_BUDDY_DATA_DIR=/srv/nex_buddy/data + +./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`,媒体、固件、码表都在这里。 +- 构建阶段 pip / npm / apt 默认走国内源,可用 `PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR` 覆盖; + `docker pull` 的镜像加速见 `docker/README.md`。 +- `--full` 时先在 `.env` 修改 `POSTGRES_PASSWORD`,不要用默认口令。 + +--- + +## 目录 + +``` +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=`(``/`