211 lines
6.4 KiB
Markdown
211 lines
6.4 KiB
Markdown
# nomadro · 数字游民旅居平台
|
||
|
||
品牌 **nomadro** — 用一行代码环游世界 🌏
|
||
|
||
**线上：** [https://nomadweb.nomadro.com](https://nomadweb.nomadro.com)
|
||
|
||
## 产品路径（环环相扣）
|
||
|
||
功能很多，但**不一次全部展示**。导航与首页按三条环串联，每页只露出「接下来」：
|
||
|
||
| 环 | 做什么 | 主要入口 |
|
||
|----|--------|----------|
|
||
| **探索 Explore** | 发现去哪 | 目的地、地图、下一站、签证；（离首页后再出现计划 / 对比） |
|
||
| **连接 Connect** | 遇见同行 | 活动 → 社区 → 匹配 → 私信 |
|
||
| **成长 Grow** | 路上做事 | 学院 → 赏金 → 工具箱（按需）→ 电子书 |
|
||
|
||
```
|
||
发现城市 ──► 写入计划 / 同城活动 ──► 社区 / 匹配 ──► 学院 / 赏金
|
||
```
|
||
|
||
- 顶栏：**探索 / 连接 / 成长** 三组下拉，**EN · 主题 · 通知** 固定在右上
|
||
- `Ctrl+K` 空态只给三环捷径；次要页面要搜索才出现
|
||
- 工具箱默认精选 +「展开全部」，不再当全站站点地图
|
||
- **连接闭环：** 活动报名需登录（可取消）；匹配 / 报名 / 讨论回复 / 赏金申请会写入通知中心；可选 ntfy 推送（`NTFY_ENABLED` + 设置里打开「推送」）
|
||
- **订阅：** 写入 PocketBase；配置 `LISTMONK_*` 后同步 Listmonk，未配置时文案如实提示「已登记」
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 前端 | Next.js 16 + React 19 | **仅 UI**；App Router、standalone |
|
||
| 后端 | FastAPI | **全部业务逻辑**（无 Next.js 业务 API Route） |
|
||
| 数据 | PocketBase | 主存储；本地可 Mock 降级 |
|
||
| 对象存储 | S3 兼容（生产 SeaweedFS） | 媒体上传 |
|
||
| 部署 | Caddy + systemd | 原生进程；勿与同机 dylive 业务互相干扰 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
nomadweb/
|
||
├── frontend/ # Next.js（页面与组件）
|
||
│ ├── src/app/ # 路由
|
||
│ ├── src/components/ # UI（含 RingNext 下一步条）
|
||
│ └── src/lib/ # api / auth / i18n / rings
|
||
├── backend/ # FastAPI
|
||
│ ├── app/routers/ # REST
|
||
│ ├── app/services/ # PocketBase、S3、城市深度等
|
||
│ └── app/data/ # Mock 降级（开发）
|
||
├── wemini/ # 微信小程序（Taro → weapp，可联网）
|
||
├── dymini/ # 抖音小程序（Taro → tt，可联网）
|
||
├── redmini/ # 小红书 miniTool（纯前端离线，禁止联网）
|
||
├── deploy/ # Caddy、systemd、env 模板
|
||
├── scripts/ # 本地开发与生产更新
|
||
└── pocketbase/ # PB 数据目录（本地可选）
|
||
```
|
||
|
||
### 小程序
|
||
|
||
| 目录 | 平台 | 联网 | 说明 |
|
||
|------|------|------|------|
|
||
| `wemini/` | 微信 | ✅ → `nomadweb.nomadro.com/api/v1` | `npm run dev:weapp` |
|
||
| `dymini/` | 抖音 | ✅ → 同上 | `npm run dev:tt` |
|
||
| `redmini/` | 小红书 | ❌ 纯离线 | `python scripts/assemble.py && python scripts/pack.py` |
|
||
|
||
Git 远程：`origin`（gitea）与 `nomadro`（[git.nomadro.cn/hackrobot/nomadweb](https://git.nomadro.cn/hackrobot/nomadweb.git)）。
|
||
|
||
## 快速开始
|
||
|
||
### 1. PocketBase（可选）
|
||
|
||
不启动则 API 使用 Mock。
|
||
|
||
```bash
|
||
docker run -d -p 8090:8090 -v ./pocketbase/pb_data:/pb_data ghcr.io/muchobien/pocketbase:latest
|
||
```
|
||
|
||
### 2. FastAPI
|
||
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
cp .env.example .env
|
||
uvicorn app.main:app --reload --port 8000
|
||
```
|
||
|
||
文档：http://localhost:8000/docs
|
||
|
||
### 3. Next.js
|
||
|
||
```bash
|
||
cd frontend
|
||
cp .env.local.example .env.local
|
||
npm install --legacy-peer-deps
|
||
npm run dev
|
||
```
|
||
|
||
访问：http://localhost:3000
|
||
|
||
```powershell
|
||
.\scripts\dev.ps1 # Windows 一键
|
||
```
|
||
|
||
## 核心功能一览
|
||
|
||
按环归类（深度页会互相引导，避免平铺）：
|
||
|
||
### 探索
|
||
| 能力 | 路径 |
|
||
|------|------|
|
||
| 地图 / 目的地 | `/#map` `/#destinations` `/destinations/[slug]` |
|
||
| 智能匹配 | 首页 CTA / `M` |
|
||
| 下一站决策 | `/next-stop` |
|
||
| 城市对比 | `/compare` |
|
||
| 旅居计划 | `/plan`（时间轴、预算、签证提醒、清单、ICS） |
|
||
| 签证指南 | `/#visa` |
|
||
|
||
### 连接
|
||
| 能力 | 路径 |
|
||
|------|------|
|
||
| 活动 RSVP / 直播间 | `/meetups` `/meetups/[id]/live` |
|
||
| 社区讨论 | `/community` |
|
||
| 游民匹配 | `/dating` |
|
||
| 私信 | `/chat` |
|
||
| 通知 | `/notifications` |
|
||
|
||
### 成长
|
||
| 能力 | 路径 |
|
||
|------|------|
|
||
| 游民学院 | `/digital` |
|
||
| 赏金任务 | `/gigs` |
|
||
| 工具箱 | `/tools`（实用小工具，非功能总览） |
|
||
| 电子书 | `/book` |
|
||
| 会员 | `/join` `/pricing` |
|
||
|
||
演示账号：`demo@nomadro.com` / `demo123`
|
||
|
||
## 环境变量
|
||
|
||
**Backend**
|
||
|
||
```env
|
||
POCKETBASE_URL=http://127.0.0.1:8090
|
||
POCKETBASE_ADMIN_EMAIL=...
|
||
POCKETBASE_ADMIN_PASSWORD=...
|
||
CORS_ORIGINS=http://localhost:3000
|
||
# S3（生产见服务器 deploy/nomadro-api.env）
|
||
```
|
||
|
||
**Frontend**
|
||
|
||
```env
|
||
NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
|
||
NEXT_PUBLIC_SITE_URL=http://localhost:3000
|
||
```
|
||
|
||
生产构建：
|
||
|
||
```env
|
||
NEXT_PUBLIC_API_URL=https://nomadweb.nomadro.com/api/v1
|
||
NEXT_PUBLIC_SITE_URL=https://nomadweb.nomadro.com
|
||
```
|
||
|
||
## Git 与部署
|
||
|
||
仓库：
|
||
- [gitea.dsx2020.com/eric/nomadweb](https://gitea.dsx2020.com/eric/nomadweb)（`origin`）
|
||
- [git.nomadro.cn/hackrobot/nomadweb](https://git.nomadro.cn/hackrobot/nomadweb.git)（`nomadro`）
|
||
|
||
当前开发分支 **`dev2`**（亦保留 `dev1` / `main`）。
|
||
|
||
```bash
|
||
git checkout dev2
|
||
git pull origin dev2
|
||
# … 改代码 …
|
||
git push origin dev2
|
||
git push nomadro dev2
|
||
python scripts/deploy_update.py # 服务器 pull + 增量构建重启
|
||
```
|
||
|
||
| 生产进程 | 地址 |
|
||
|----------|------|
|
||
| 网站 | https://nomadweb.nomadro.com |
|
||
| `nomadro-web` | `127.0.0.1:3055` |
|
||
| `nomadro-api` | `127.0.0.1:8055` |
|
||
| PocketBase | `127.0.0.1:8090` |
|
||
| S3 | `s3.nomadro.com` → SeaweedFS |
|
||
|
||
**注意：** 同机还跑有 [dylive.nomadro.com](https://dylive.nomadro.com/)（`/opt/douyinWEB`）。更新 nomadweb 时**不要**改动 / 限流 / 杀掉直播相关进程。
|
||
|
||
密钥仅放服务器 `deploy/nomadro-api.env`（模板见 `*.env.example`），勿提交。
|
||
|
||
## 快捷键
|
||
|
||
| 按键 | 功能 |
|
||
|------|------|
|
||
| `Ctrl+K` | 全局搜索（三环捷径） |
|
||
| `M` | 智能匹配 |
|
||
| `P` | 旅居计划 |
|
||
| `T` | 工具箱 |
|
||
| `?` | 帮助 |
|
||
| `Esc` | 关闭弹窗 |
|
||
|
||
## 相关
|
||
|
||
- 迭代说明：[/changelog](https://nomadweb.nomadro.com/changelog)
|
||
- 前端脚手架说明：`frontend/README.md`（以本文件为准）
|
||
|
||
## License
|
||
|
||
MIT
|