# 游牧中国 NomadCNA 项目与服务器部署报告 生成时间：2026-06-06 23:16 CST 服务器时区：Asia/Shanghai / CST +0800 项目路径：`/home/ubuntu/gitlab-instance-0a899031_cnomadcna` Git 分支：`test2` 最新提交：`00b1c8e`，2026-06-06 23:05:17 +0800 报告范围：当前仓库代码、前端/后端/数据服务、服务器上实际运行的相关服务、反向代理、端口、构建状态、运维风险与后续建议。 敏感信息处理：本报告只记录环境变量名、用途、路径、端口和域名，不记录任何密码、Token、Access Key、Secret、数据库连接串原文。 ## 1. 项目定位 NomadCNA / 游牧中国是一个面向数字游民的中文优先、英文可切换的一站式网站，当前定位可以概括为： - 数字游民城市决策平台：展示中国城市的成本、网速、安全、气候、社区活跃度、标签和详情。 - 数字游民社区入口：提供报名、登录、会员、资料录入、同城活动、交友匹配、站内消息。 - 数字游民服务市场：提供共享办公、城市落地顾问、保障类服务、赏金任务、反馈和咨询线索。 - 数字游民内容与工具：电子书、视频、报告、AI 助手、FIRE/汇率/签证/气候工具。 - 生产部署站点：当前主域为 `nomadro.cn` / `www.nomadro.cn`，PocketBase 为 `pocketbase.nomadro.cn`，FastAPI 为 `api.nomadro.cn`。 当前项目已经不是纯前端展示站，已经具备“前端 + Next.js API + FastAPI + PocketBase + 支付 + 上传 + 消息 + 监控”的完整早期产品架构。 ## 2. 访问地址与部署入口 ### 2.1 对外域名 | 域名 | 当前用途 | 反向代理目标 | HTTPS 状态 | | --- | --- | --- | --- | | `https://nomadro.cn` | 游牧中国主站 | `127.0.0.1:4002` | 已配置证书 | | `https://www.nomadro.cn` | 游牧中国主站 | `127.0.0.1:4002` | 已配置证书 | | `http://api.nomadro.cn` | FastAPI 后端 API | `127.0.0.1:8000` | 当前只看到 HTTP 配置 | | `https://pocketbase.nomadro.cn` | PocketBase REST API 与后台 | `127.0.0.1:8090` | 已配置证书 | | `https://umami.nomadro.cn` | Umami 统计 | `127.0.0.1:9280` | 已配置证书 | | `http://ntfy.nomadro.cn` | ntfy 推送服务 | `127.0.0.1:9180` | 当前只看到 HTTP 配置 | | `http://netdata.nomadro.cn` | Netdata 监控面板 | `127.0.0.1:19999` | 当前只看到 HTTP 配置，已配置 Basic Auth | ### 2.2 本机端口 | 端口 | 监听地址 | 服务 | 说明 | | --- | --- | --- | --- | | `4002` | `*:4002` | NomadCNA Next.js | 生产前端，systemd 管理 | | `8000` | `127.0.0.1:8000` | NomadCNA FastAPI | 后端 API，systemd 管理 | | `8090` | `127.0.0.1:8090` | PocketBase | 本站主数据服务 | | `9280` | `127.0.0.1:9280` | Umami | 统计分析服务 | | `9180` | `127.0.0.1:9180` | ntfy Docker 容器 | 通知推送服务 | | `19999` | `127.0.0.1:19999` | Netdata | 宿主机监控 | | `80/443` | `0.0.0.0` | Nginx | 站点反向代理 | | `3306` | `0.0.0.0` | MariaDB/MySQL | 宝塔/其他服务使用，非当前 NomadCNA 主数据 | | `5432` | `127.0.0.1` | PostgreSQL 16 | Umami 使用 | | `21` | `0.0.0.0` | pure-ftpd | FTP 服务 | | `888` | `0.0.0.0` | 宝塔面板 Nginx | 管理面板 | | `36711` | `0.0.0.0` | 宝塔面板 webserver | 管理面板相关 | | `7000/8999` | `*` | frp-panel | 同机运行的穿透/面板服务 | ### 2.3 健康检查结果 已验证： - `http://127.0.0.1:8000/api/health` 返回 `200`，服务名为 `NomadCNA FastAPI`。 - `http://127.0.0.1:4002/zh` 返回 `200`，Next.js 页面可访问。 - `http://127.0.0.1:8090/api/health` 返回 `200`，PocketBase 可访问。 - `https://nomadro.cn` 返回 `307` 到 `/zh`，随后返回 `200`。 - `https://www.nomadro.cn` 返回 `307` 到 `/zh`，随后返回 `200`。 - `http://api.nomadro.cn/api/health` 返回 FastAPI 健康信息。 - `https://pocketbase.nomadro.cn/api/health` 返回 `200`。 ## 3. 技术栈 ### 3.1 前端 - Next.js `16.1.6` - React `19.2.3` - React DOM `19.2.3` - TypeScript `^5` - Tailwind CSS `^4` - ECharts `^6.0.0` - PocketBase JS SDK `^0.26.8` - MinIO SDK `^8.0.7` - 包管理器：`pnpm 10.25.0` - Node.js：`v22.13.1` ### 3.2 后端 - FastAPI - Uvicorn - httpx - python-multipart - PyJWT - passlib[bcrypt] - Pydantic v2 - Python `3.12.3` ### 3.3 数据与存储 - PocketBase：主业务数据库，运行在 `/opt/pocketbase`。 - PocketBase 数据目录：`/opt/pocketbase/pb_data`。 - PocketBase 迁移目录：`/opt/pocketbase/pb_migrations`。 - MinIO：代码中已接入，Docker compose 中也有 `nomadro-minio` 配置，但当前 `docker ps` 只看到 `nomadro-ntfy` 正在运行。 - 本地上传：FastAPI 挂载 `backend/uploads`，Next.js 上传接口使用 MinIO。 ### 3.4 代理、运维与监控 - Nginx：宝塔路径 `/www/server/nginx`，站点配置在 `/www/server/panel/vhost/nginx/`。 - systemd：管理 Next.js、FastAPI、PocketBase、Umami、Netdata 等服务。 - Docker：当前运行 `nomadro-ntfy` 容器。 - Netdata：宿主机实时监控。 - Umami：站点访问统计。 - 宝塔面板相关服务：Nginx、pure-ftpd、MariaDB、站点统计、面板防火墙。 ## 4. 仓库结构 项目根目录主要文件： | 路径 | 说明 | | --- | --- | | `app/` | Next.js App Router 应用主体 | | `app/[locale]/` | 中英文路由页面，支持 `/zh` 和 `/en` | | `app/api/` | Next.js API routes，主要处理认证、支付、上传、会员状态 | | `app/components/` | Navbar、Hero、城市卡片、弹窗、菜单、通知铃等组件 | | `app/context/` | 主题和语言 Context | | `app/data/` | 城市、博客、招聘等 fallback/mock 数据 | | `app/lib/` | API 客户端、PocketBase、支付、MinIO、图表、Cookie 等工具 | | `backend/` | FastAPI 本地 API 服务 | | `config/` | 站点、导航、域名、服务、首页、页脚、筛选配置 | | `i18n/` | 国际化路由和导航适配 | | `messages/` | 中文和英文文案 | | `public/` | 静态资源 | | `next.config.ts` | Next.js 配置和 API rewrite | | `proxy.ts` | locale 重定向代理 | | `package.json` | 前端依赖和脚本 | | `backend/requirements.txt` | Python 后端依赖 | | `cnomadcna.sh` | 生产 Next.js systemd 启动脚本 | | `PROJECT_ANALYSIS_REPORT.md` | 旧分析报告 | | `NOMADCNA_PROJECT_DEPLOYMENT_REPORT.md` | 当前报告 | 项目体积：当前仓库目录约 `746M`，包含 `.next`、`node_modules`、`backend/.venv` 等运行产物。 ## 5. 前端应用结构 ### 5.1 国际化 - 支持语言：`zh`、`en`。 - 默认语言：`zh`。 - URL 策略：总是带 locale 前缀。 - `proxy.ts` 会将无 locale 的页面请求重定向到 `/zh`。 - `/api`、`/_next`、静态文件和带扩展名路径不做 locale 重定向。 ### 5.2 主要页面 当前 `app/[locale]` 下页面包括： | 页面 | 用途 | | --- | --- | | `/` | 首页，城市列表、内容入口、统计、活动、路线、社区模块 | | `/dashboard` | 下一站推荐，根据预算、网速、气候、标签推荐城市 | | `/city/[slug]` | 城市详情动态页 | | `/meetups` | 线下活动列表 | | `/meetups/host` | 发起活动 | | `/dating` | 智能匹配、交友、伙伴、室友、合伙人 | | `/tools` | 汇率、税务估算、签证倒计时、FIRE、气候匹配 | | `/ai` | AI 助手，基于城市数据库返回建议 | | `/gigs` | 赏金任务发布和接单 | | `/services` | 数字游民服务咨询入口 | | `/pricing` | Free / Basic / Pro 定价展示 | | `/join` | 社区报名、资料录入、上传、支付跳转 | | `/join/paid` | 支付回跳与会员开通确认 | | `/messages` | 站内消息中心 | | `/settings/notifications` | 通知偏好设置 | | `/report`、`/report/data` | 数字游民报告 | | `/map` | 成员地图 | | `/blog` | 博客 | | `/ebooks/[slug]` | 电子书动态页 | | `/videos/[slug]` | 视频动态页 | | `/app` | App 下载/介绍页 | | `/feedback` | 反馈 | | `/discuss` | 讨论社区 | | `/jobs`、`/careers` | 招聘/职业 | | `/about`、`/contact`、`/press`、`/support`、`/help` | 基础内容页 | | `/terms`、`/privacy`、`/cookies`、`/safety`、`/guidelines` | 法务和社区规则 | ### 5.3 首页数据策略 首页当前采用“线上 API 优先、fallback 静态数据兜底”的方式： - `/api/cities`：城市列表。 - `/api/content/home`：首页内容卡片。 - `/api/stats/overview`：城市、游民、活动、成本、讨论等统计。 - `/api/profiles`：成员头像和正在旅行的人。 - `/api/meetups`：近期活动。 - `/api/discussions`：热门讨论。 - `/api/routes`：热门路线。 如果 API 请求失败，会回退到 `config/home.config.ts` 和 `app/data/cities.ts` 内的本地数据。这让站点在后端短暂不可用时仍能展示基本内容。 ### 5.4 导航与站点配置 站点标题：`游牧中国 NomadCNA - 数字游民生活操作系统` 站点描述：数字游民的一站式生活操作系统，覆盖城市决策、税务签证、智能匹配、赏金任务。 主导航包括： - 城市 - 下一站 - 聚会 - 社区 - 工具箱 - AI - 赏金 - 会员 - 探索 ## 6. API 层结构 当前 API 有两层，需要明确区分。 ### 6.1 Next.js API routes `app/api` 下当前存在： | 路径 | 用途 | | --- | --- | | `/api/auth/me` | 读取登录态、刷新 PocketBase auth、返回 VIP 状态 | | `/api/auth/logout` | 清除登录 Cookie | | `/api/auth/sync-session` | 支付后同步 token 到 Cookie | | `/api/auth/change-password` | 修改密码 | | `/api/join` | 提交报名资料到 PocketBase 指定集合 | | `/api/join/status` | 检查是否已经提交报名 | | `/api/upload-media` | 通过 MinIO 上传图片/视频 | | `/api/vip/check` | 检查 `site_vip` 会员记录 | | `/api/pay` | 创建支付订单，调用 payjsapi / ZPay / XorPay | | `/api/pay/status` | 查询支付状态 | | `/api/meetup/check-user` | 检查用户是否存在和是否 VIP | | `/api/meetup/ensure-user` | 确保用户存在 | | `/api/meetup/complete-order` | 支付成功后确认订单并开通 VIP | | `/api/meetup/need-password-change` | 检查是否需要改默认密码 | | `/api/meetup/set-needs-password-change` | 设置需要改密码 | | `/api/geo/china` | 拉取中国地图 GeoJSON | ### 6.2 FastAPI 后端 FastAPI 运行在 `127.0.0.1:8000`，服务名 `cnomadcna-api.service`。主要接口包括： | 路径 | 用途 | | --- | --- | | `/api/health` | 健康检查 | | `/api/auth/register` | 注册并设置 session | | `/api/auth/login` | 登录并设置 session | | `/api/auth/me` | 当前用户和会员状态 | | `/api/auth/logout` | 清除 session | | `/api/auth/change-password` | 修改密码 | | `/api/meetup/check-user` | 检查用户和会员 | | `/api/meetup/ensure-user` | 创建或登录用户 | | `/api/meetup/complete-order` | 本地订单完成和 membership 写入 | | `/api/vip/check` | 根据 `memberships` 检查 VIP | | `/api/join` | 提交会员申请 | | `/api/join/status` | 报名状态 | | `/api/upload-media` | 本地上传到 `backend/uploads` | | `/api/pay` | 本地开发支付 | | `/api/pay/status` | 本地开发支付状态 | | `/api/cities` | 城市列表 | | `/api/cities/{slug}` | 城市详情 | | `/api/content/home` | 首页内容 | | `/api/content/{slug}` | 内容详情 | | `/api/notifications` | 消息列表和筛选 | | `/api/notifications/unread-count` | 未读数 | | `/api/notifications/{id}/read` | 标记已读 | | `/api/notifications/{id}/unread` | 标记未读 | | `/api/notifications/{id}/archive` | 归档 | | `/api/notifications/{id}/restore` | 恢复 | | `/api/notifications/{id}/pin` | 置顶 | | `/api/notifications/mark-all-read` | 全部已读 | | `/api/notifications/preferences` | 读取/保存通知偏好 | | `/api/recommendations/next-stop` | 下一站推荐 | | `/api/routes` | 游牧路线 | | `/api/services` | 服务列表 | | `/api/services/leads` | 服务咨询线索 | | `/api/downloads/{filename}` | 下载 PDF/Zip 等资源 | | `/api/meetups` | 活动列表和创建 | | `/api/discussions` | 讨论列表和创建 | | `/api/gigs` | 赏金列表和发布 | | `/api/gigs/{gig_id}/apply` | 接单 | | `/api/profiles` | 成员资料 | | `/api/matches/swipes` | 匹配滑动记录 | | `/api/feedback` | 反馈 | | `/api/stats/member-map` | 成员地图统计 | | `/api/stats/overview` | 总览统计 | | `/api/stats/city-ranking` | 城市排行 | | `/api/geo/china` | 地图数据 | | `/api/ai/assistant` | AI 助手模拟响应 | ### 6.3 Next.js rewrite `next.config.ts` 把部分 `/api/*` 路径 rewrite 到 FastAPI： - health - cities - content - notifications - recommendations - routes - services - downloads - meetups - discussions - gigs - profiles - matches - feedback - stats - ai 这意味着： - 上面列出的业务数据 API 会由 FastAPI 处理。 - Next.js 自身的 `/api/auth/*`、`/api/pay/*`、`/api/join/*`、`/api/upload-media`、`/api/vip/check` 等仍由 Next.js API routes 处理。 - `app/lib/api-client.ts` 默认 `NEXT_PUBLIC_API_BASE_URL || http://127.0.0.1:8000`。生产环境必须保证 `NEXT_PUBLIC_API_BASE_URL` 指向公网可访问的 API 地址，例如 `http://api.nomadro.cn` 或未来的 `https://api.nomadro.cn`，否则浏览器会尝试请求访问者自己机器的 `127.0.0.1:8000`。 ## 7. PocketBase 数据模型 ### 7.1 PocketBase 服务 PocketBase systemd 配置： - 服务名：`pocketbase.service` - 工作目录：`/opt/pocketbase` - 启动命令：`/opt/pocketbase/pocketbase serve --http=127.0.0.1:8090 --dir=/opt/pocketbase/pb_data --origins=https://nomadro.cn,https://www.nomadro.cn,https://pocketbase.nomadro.cn` - 数据目录：`/opt/pocketbase/pb_data` - 迁移目录：`/opt/pocketbase/pb_migrations` - 当前状态：active/running PocketBase 数据库文件： - `/opt/pocketbase/pb_data/data.db` - `/opt/pocketbase/pb_data/auxiliary.db` - `/opt/pocketbase/pb_data/types.d.ts` ### 7.2 初始化脚本中的集合 `backend/init_db.py` 定义并初始化以下集合： | 集合 | 用途 | | --- | --- | | `cities` | 城市主数据，包括 slug、名称、成本、网速、安全、气候、坐标、标签 | | `city_details` | 城市详情 JSON，包括指南、优缺点、评价、成本、天气、趋势等 | | `profiles` | 成员资料和匹配展示 | | `member_applications` | 社区报名资料 | | `memberships` | FastAPI 使用的会员记录 | | `orders` | FastAPI 本地订单 | | `media_assets` | 上传媒体记录 | | `meetups` | 线下活动 | | `discussions` | 讨论帖 | | `gigs` | 赏金任务 | | `gig_applications` | 接单申请 | | `services` | 服务市场条目 | | `service_leads` | 服务咨询线索 | | `routes` | 游牧路线 | | `recommendation_logs` | 下一站推荐日志 | | `notifications` | 站内通知 | | `notification_receipts` | 通知已读/归档/置顶状态 | | `notification_preferences` | 通知偏好 | | `feedback` | 用户反馈 | | `swipes` | 交友匹配滑动行为 | | `content_items` | 电子书、视频、App、指南等内容卡片 | ### 7.3 种子数据 种子数据覆盖： - 18 个中国数字游民城市，包括大理、成都、深圳、上海、杭州、厦门、北京、广州、重庆、昆明、三亚、丽江、西安、南京、长沙、青岛、苏州、珠海。 - 城市成本、网速、安全、气候、经纬度、标签和英文描述。 - 首页内容：数字游民落地手册、访谈视频、NomadCNA App、数字游民指南。 - 活动、讨论、赏金、成员资料、服务、路线、通知。 - 典型服务：远程工作者医疗与旅行保障、共享办公通行证、城市落地顾问。 - 典型路线：云南慢生活线、湾区创业线、江南互联网线。 ### 7.4 会员模型一致性风险 当前存在两套会员判断模型： - FastAPI 的 `/api/vip/check` 和 `/api/auth/me` 使用 `memberships` 集合。 - Next.js 的 `/api/vip/check`、`/api/auth/me`、`/api/meetup/complete-order` 使用 `site_vip` 集合。 - `/opt/pocketbase/pb_migrations` 当前列出的迁移包含 `memberships`，未在本次扫描输出中看到 `site_vip` 迁移文件。 这会带来风险： - 如果生产 PocketBase 中没有 `site_vip` 集合，Next.js 会员检查会一直返回非 VIP。 - 如果支付完成只写 `site_vip`，FastAPI 的会员检查不会识别。 - 如果某些页面走 Next.js API，某些页面走 FastAPI API，会员状态可能不一致。 建议统一为一套会员集合，或明确 `site_vip` 是跨站会员表、`memberships` 是旧表，并补充迁移、同步逻辑和文档。 ## 8. 支付与报名链路 ### 8.1 报名流程 主要页面：`/zh/join` 流程： 1. 用户填写昵称、性别、感情状态、职业、简介、微信、学历、毕业年份、手机号、图片/视频。 2. 页面先检查 `/api/auth/me`。 3. 未登录则打开认证弹窗。 4. 已登录后调用 `/api/join` 写入报名资料。 5. 再调用 `/api/vip/check`。 6. 如果不是 VIP，则调用 `/api/pay` 跳转支付。 7. 支付成功回跳 `/join/paid`。 8. `/join/paid` 根据 `order_id` 调用 `/api/meetup/complete-order`。 9. 订单确认后同步登录态、触发 `auth:updated` 和 `vip:updated` 事件。 10. 新用户会显示默认密码提示，并允许修改密码。 ### 8.2 支付配置 代码支持： - `zpay` - `xorpay` - payjsapi 风格 API - PC / H5 / 微信浏览器支付环境判断 - 微信内强制走 XorPay 的逻辑 - ZPay 二维码轮询和支付成功后自动确认 关键环境变量名： - `PAYMENT_API_URL` - `PAYMENT_PROVIDER` - `PAYMENT_DEFAULT_AMOUNT` - `PAYMENT_DEFAULT_TYPE` - `PAYMENT_JOIN_AMOUNT` - `PAYMENT_JOIN_TYPE` - `ZPAY_SUBMIT_URL` - `NEXT_PUBLIC_SITE_ID` `config/domain.config.ts` 中有保护逻辑：生产环境如果 `PAYMENT_API_URL` 指向 localhost，会使用 `https://api.${ROOT_DOMAIN}`。 ### 8.3 安全注意点 - 新用户默认密码当前是 `12345678`，且页面会展示和复制该密码。这适合 MVP，但生产上存在弱口令风险。 - 建议改为一次性随机临时密码、一次性登录链接，或强制首次设置密码后才完成登录。 - 支付确认依赖订单 ID 格式解析，建议补充订单表记录、签名校验、回调审计和重复开通幂等测试。 ## 9. 上传与对象存储 当前存在两套上传实现： ### 9.1 Next.js MinIO 上传 路径：`app/api/upload-media/route.ts` - 接收 `multipart/form-data`。 - 文件大小限制：20MB。 - 生成对象 key：`{uploadPrefix}/{timestamp}_{random}.{ext}`。 - 调用 `app/lib/minio/client.ts` 的 `putObject`。 - 返回公开 URL。 关键环境变量： - `MINIO_ENDPOINT` - `MINIO_PORT` - `MINIO_USE_SSL` - `MINIO_BUCKET` - `MINIO_ACCESS_KEY` - `MINIO_SECRET_KEY` - `MINIO_REGION` - `MINIO_PUBLIC_URL` - `MINIO_UPLOAD_PREFIX` ### 9.2 FastAPI 本地上传 路径：`backend/main.py` 的 `/api/upload-media` - 文件大小限制：20MB。 - 写入 `settings.upload_dir`，默认 `backend/uploads`。 - 通过 `/uploads/{name}` 静态路径提供访问。 - 同时写 `media_assets` 集合。 ### 9.3 当前部署观察 - Docker compose 中定义了 `nomadro-minio`，端口计划为 `127.0.0.1:9100` 和 `127.0.0.1:9101`。 - 但当前 `docker ps` 只看到 `nomadro-ntfy` 运行，未看到 MinIO 容器。 - `.env.local` 中存在 MinIO 配置项，但报告未记录敏感值。 建议尽快确认生产上传到底走 MinIO 还是 FastAPI 本地目录，并统一一条路径。 ## 10. systemd 服务 ### 10.1 NomadCNA Next.js 服务名：`cnomadcna.service` 状态：enabled / active / running 工作目录：`/home/ubuntu/gitlab-instance-0a899031_cnomadcna` 启动脚本：`/home/ubuntu/gitlab-instance-0a899031_cnomadcna/cnomadcna.sh` 环境： - `NODE_ENV=production` - `HOSTNAME=0.0.0.0` - `PORT=4002` 启动命令最终为： ```bash pnpm start ``` `package.json` 中 `start` 为： ```bash next start ``` 当前运行： - 主进程：`node /usr/local/bin/pnpm start` - 子进程：`next-server (v16.1.6)` - 监听：`*:4002` - 最近启动：2026-06-06 21:50 CST ### 10.2 NomadCNA FastAPI 服务名：`cnomadcna-api.service` 状态：enabled / active / running 工作目录：`/home/ubuntu/gitlab-instance-0a899031_cnomadcna` 环境文件：`/home/ubuntu/gitlab-instance-0a899031_cnomadcna/backend/.env` 启动命令： ```bash /home/ubuntu/gitlab-instance-0a899031_cnomadcna/backend/.venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port 8000 ``` 当前运行： - 主进程：`uvicorn` - 监听：`127.0.0.1:8000` - 最近启动：2026-06-06 21:46 CST ### 10.3 PocketBase 服务名：`pocketbase.service` 状态：enabled / active / running 工作目录：`/opt/pocketbase` 启动命令： ```bash /opt/pocketbase/pocketbase serve --http=127.0.0.1:8090 --dir=/opt/pocketbase/pb_data --origins=https://nomadro.cn,https://www.nomadro.cn,https://pocketbase.nomadro.cn ``` 监听：`127.0.0.1:8090` ### 10.4 Umami 服务名：`umami.service` 状态：enabled / active / running 用户：`umami` 工作目录：`/opt/umami` 环境文件：`/opt/umami/.env.production` 启动命令： ```bash /usr/local/bin/node /opt/umami/.next/standalone/server.js ``` 监听：`127.0.0.1:9280` 注意：最近日志有 Next.js Server Action 找不到的错误，可能来自旧前端请求或版本切换后的残留请求。 ### 10.5 Netdata 服务名：`netdata.service` 状态：enabled / active / running 监听：`127.0.0.1:19999` Nginx 反代：`netdata.nomadro.cn`，带 Basic Auth。 ### 10.6 其他同机服务 | 服务 | 状态 | 说明 | | --- | --- | --- | | `nginx` | running | 宝塔 Nginx，主反向代理 | | `mysqld` | running | MariaDB/MySQL | | `postgresql@16-main` | running | PostgreSQL 16，Umami 使用 | | `docker` / `containerd` | running | Docker 运行时 | | `pure-ftpd` | running | FTP | | `frpp.service` | running | frp-panel | | `site_total.service` | running | 宝塔站点统计 | | `BT-FirewallServices.service` | running | 宝塔防火墙服务 | ## 11. Nginx 反向代理 Nginx 配置路径：`/www/server/panel/vhost/nginx/` ### 11.1 主站 配置文件：`/www/server/panel/vhost/nginx/www.nomadro.cn.conf` - upstream：`nomadro_nextjs` - upstream 地址：`127.0.0.1:4002` - `80` 端口：重定向到 HTTPS。 - `443 ssl http2`：代理到 Next.js。 - 证书：`/etc/letsencrypt/live/nomadro.cn/fullchain.pem` - 日志： - `/www/wwwlogs/www.nomadro.cn.log` - `/www/wwwlogs/www.nomadro.cn.error.log` ### 11.2 FastAPI 配置文件：`/www/server/panel/vhost/nginx/api.nomadro.cn.conf` - upstream：`nomadro_api` - upstream 地址：`127.0.0.1:8000` - 当前只看到 HTTP server 配置。 - 日志： - `/www/wwwlogs/api.nomadro.cn.log` - `/www/wwwlogs/api.nomadro.cn.error.log` 建议为 `api.nomadro.cn` 配置 HTTPS，尤其是认证、支付、会员接口需要安全传输。 ### 11.3 PocketBase 配置文件：`/www/server/panel/vhost/nginx/pocketbase.nomadro.cn.conf` - upstream：`nomadro_pocketbase` - upstream 地址：`127.0.0.1:8090` - `80` 重定向到 HTTPS。 - `443 ssl http2` 代理到 PocketBase。 - 证书：`/etc/letsencrypt/live/pocketbase.nomadro.cn/fullchain.pem` ### 11.4 Umami 配置文件：`/www/server/panel/vhost/nginx/umami.nomadro.cn.conf` - upstream：`nomadro_umami` - upstream 地址：`127.0.0.1:9280` - `80` 重定向到 HTTPS。 - `443 ssl http2` 代理到 Umami。 ### 11.5 ntfy 配置文件：`/www/server/panel/vhost/nginx/ntfy.nomadro.cn.conf` - upstream：`nomadro_ntfy` - upstream 地址：`127.0.0.1:9180` - 当前只看到 HTTP server 配置。 - 建议后续补 HTTPS。 ### 11.6 Netdata 配置文件：`/www/server/panel/vhost/nginx/netdata.nomadro.cn.conf` - upstream：`nomadro_netdata` - upstream 地址：`127.0.0.1:19999` - 使用 Basic Auth 文件：`/www/server/panel/vhost/nginx/netdata.nomadro.cn.htpasswd` - 当前只看到 HTTP server 配置。 ### 11.7 Nginx 配置校验 已执行 Nginx 配置测试： ```bash nginx -t ``` 结果：syntax ok，test successful。 ## 12. TLS 证书 Certbot 当前证书： | 证书名 | 域名 | 到期时间 | | --- | --- | --- | | `nomadro.cn` | `nomadro.cn`, `www.nomadro.cn` | 2026-09-04 12:34:54 UTC | | `pocketbase.nomadro.cn` | `pocketbase.nomadro.cn` | 2026-09-04 12:49:52 UTC | | `umami.nomadro.cn` | `umami.nomadro.cn` | 2026-09-04 13:58:40 UTC | 当前未看到 `api.nomadro.cn`、`ntfy.nomadro.cn`、`netdata.nomadro.cn` 的 Certbot 证书。 ## 13. Docker 服务 当前 `docker ps` 只看到： | 容器 | 镜像 | 状态 | 端口 | | --- | --- | --- | --- | | `nomadro-ntfy` | `binwiederhier/ntfy:latest` | running | `127.0.0.1:9180->80` | `/opt/nomadro-services/docker-compose.yml` 中还定义了： - `nomadro-minio`：对象存储，计划监听 `127.0.0.1:9100` / `127.0.0.1:9101`。 - `nomadro-ntfy`：通知推送。 - `nomadro-uptime-kuma`：可用性监控，计划监听 `127.0.0.1:9301`。 - `nomadro-netdata`：容器版 Netdata，计划监听 `127.0.0.1:9199`。 - `nomadro-mirotalk`：视频会议，计划监听 `127.0.0.1:9300`。 实际运行和 compose 定义不完全一致。当前宿主机 systemd 版 Netdata 正在运行，Docker 版 Netdata 未运行。MinIO、Uptime Kuma、MiroTalk 当前也未在 `docker ps` 中出现。 ## 14. 服务器资源与安全边界 ### 14.1 系统信息 - 主机名：`VM-0-16-ubuntu` - 云厂商：Tencent Cloud CVM - 操作系统：Ubuntu 24.04.4 LTS - 内核：Linux 6.8.0-101-generic - 架构：x86_64 - 运行时间：约 6 天 9 小时 ### 14.2 资源状态 - 内存：3.6Gi，总可用约 2.5Gi。 - Swap：1.9Gi，已用约 512Mi。 - 根分区：69G，总用量 17G，可用 50G，使用率 25%。 - 当前负载较低。 ### 14.3 防火墙 UFW 状态：active 默认策略： - incoming：deny - outgoing：allow - routed：deny 当前开放端口包括： - `80` - `443` - `22` - `21` - `20/tcp` - `888/tcp` - `8080` - `36711/tcp` - `39000:40000/tcp` - 以及一个 `8` 规则 风险点： - FTP 端口 `20/21` 和被动端口段 `39000:40000` 对公网开放。 - 宝塔面板端口 `888`、`36711` 对公网开放。 - `22` 对公网开放。 - `3306` MariaDB 当前监听 `0.0.0.0:3306`，即便 UFW 未列出 `3306` 开放，也建议数据库服务改为只监听本地或确保云防火墙关闭公网访问。 ## 15. 环境变量与配置 ### 15.1 根目录 `.env.local` 当前项目根目录存在 `.env.local`，生产构建会加载它。已确认其包含以下类别变量： - 根域名：`ROOT_DOMAIN`、`NEXT_PUBLIC_ROOT_DOMAIN` - PocketBase：`NEXT_PUBLIC_POCKETBASE_URL`、`POCKETBASE_URL` - 支付：`PAYMENT_API_URL`、`PAYMENT_PROVIDER`、`PAYMENT_DEFAULT_AMOUNT`、`PAYMENT_JOIN_AMOUNT` - 站点：`NEXT_PUBLIC_SITE_ID`、`NEXT_PUBLIC_SITE_URL`、`NEXT_PUBLIC_API_BASE_URL` - MinIO：`MINIO_ENDPOINT`、`MINIO_PORT`、`MINIO_USE_SSL` - PocketBase 管理员：`POCKETBASE_EMAIL`、`POCKETBASE_PASSWORD` ### 15.2 FastAPI `backend/.env` 当前 systemd 会读取 `backend/.env`，包含： - `PB_URL` - `PB_ADMIN_EMAIL` - `PB_ADMIN_PASSWORD` - `API_COOKIE_NAME` - `FRONTEND_ORIGINS` - `UPLOAD_DIR` - `DEV_AUTO_PAY` ### 15.3 敏感文件 Git 风险 `git ls-files` 显示以下文件被 Git 跟踪： - `.env.example` - `.env.local` - `.env.local.bak.20260606212903` - `backend/.env.example` 其中 `.env.local` 和 `.env.local.bak.*` 不应被提交。`.env.example` 当前也包含真实样式的敏感配置，不应放真实账号或密码。 建议： 1. 立即将 `.env.local` 和 `.env.local.bak.*` 从 Git 索引移除。 2. 将 `.gitignore` 中的 `# .env*` 改为实际忽略规则。 3. 重置已经暴露过的 PocketBase、支付、MinIO 等所有密钥。 4. `.env.example` 只保留占位符，例如 `POCKETBASE_PASSWORD=replace_me`。 ## 16. 构建与质量状态 ### 16.1 `pnpm build` 已执行： ```bash pnpm build ``` 结果：通过。 构建输出： - Next.js `16.1.6` - 成功编译。 - TypeScript 检查通过。 - 静态页面生成：85 个。 - 路由包含 `/zh`、`/en` 以及所有主要页面。 - API route 均被识别为动态服务端路由。 注意：本次构建刷新了 `.next` 产物时间戳，`.next/BUILD_ID` 时间为 2026-06-06 23:16 CST。 ### 16.2 `pnpm lint` 已执行： ```bash pnpm lint ``` 结果：失败，`7 errors / 31 warnings`。 主要错误： - `app/[locale]/dashboard/page.tsx`：React Hooks 新规则提示 effect 内同步 `setLoading(true)`。 - `app/api/meetup/complete-order/route.ts`：`userId` 和 `payType` 应使用 `const`。 - `app/components/CityModal.tsx`：effect 内同步 `setMounted(true)`。 - `app/components/SiteMenu.tsx`：effect 内同步 `setUserEmail(...)`。 - `app/components/ThemeToggle.tsx`：effect 内同步 `setMounted(true)`。 - `app/context/ThemeContext.tsx`：effect 内同步设置 theme/mounted。 主要警告： - 多处使用 ``，Next.js 建议使用 `next/image`。 - 若干未使用变量。 - `MembersMap.tsx` 有 hook 依赖提示。 结论： - 当前源码可以生产构建并运行。 - 但 lint 不通过，CI 若以 lint 为发布门槛会失败。 - 建议先修复 7 个 lint error，再逐步处理图片优化和未使用变量。 ## 17. 当前运行日志观察 ### 17.1 Next.js 最近重启后正常启动，监听 `4002`。日志有 Node.js deprecation warning： - `util._extend` 已废弃，建议依赖链后续升级或等待 Next/相关依赖修复。 ### 17.2 FastAPI 最近启动正常。早些时候曾出现： - `PocketBase 404: Missing collection context.` 随后 PocketBase 集合初始化后，`/api/cities`、`/api/profiles`、`/api/content/home` 已返回 `200`。 当前还看到外部或代理访问 `/` 和 `/favicon.ico` 到 FastAPI 时返回 `404`，这是正常的，因为 FastAPI 只提供 `/api/*` 和 `/uploads/*`。 ### 17.3 PocketBase 启动正常，REST API 和 Dashboard 均监听 `127.0.0.1:8090`。 ### 17.4 Umami 服务运行中，但日志出现 `Failed to find Server Action "000000..."`。可能是部署切换后旧请求、缓存或探测请求造成，需要后续观察。 ### 17.5 宝塔 site_total `site_total.service` 日志持续出现写 HyperLogLog 文件失败，路径类似： - `/www/server/site_total/data/hll/2026-06-04/www.nomadro.cn.hll` - `/www/server/site_total/data/hll/2026-06-04/ALL.hll` 这不直接影响 NomadCNA 主站，但会影响宝塔站点统计准确性。 ## 18. 运维命令速查 ### 18.1 项目前端 ```bash cd /home/ubuntu/gitlab-instance-0a899031_cnomadcna pnpm install pnpm build pnpm start ``` 开发模式： ```bash pnpm dev ``` 注意：`package.json` 中 dev 实际端口是 `3001`： ```bash next dev -p 3001 -H 0.0.0.0 ``` ### 18.2 后端 ```bash cd /home/ubuntu/gitlab-instance-0a899031_cnomadcna source backend/.venv/bin/activate pip install -r backend/requirements.txt uvicorn backend.main:app --host 127.0.0.1 --port 8000 ``` 初始化 PocketBase 集合和种子： ```bash cd /home/ubuntu/gitlab-instance-0a899031_cnomadcna source backend/.venv/bin/activate python -m backend.init_db ``` ### 18.3 systemd 查看状态： ```bash systemctl status cnomadcna.service --no-pager -l systemctl status cnomadcna-api.service --no-pager -l systemctl status pocketbase.service --no-pager -l systemctl status umami.service --no-pager -l ``` 重启服务： ```bash systemctl restart cnomadcna.service systemctl restart cnomadcna-api.service systemctl restart pocketbase.service ``` 查看日志： ```bash journalctl -u cnomadcna.service -n 100 --no-pager journalctl -u cnomadcna-api.service -n 100 --no-pager journalctl -u pocketbase.service -n 100 --no-pager journalctl -u umami.service -n 100 --no-pager ``` ### 18.4 Nginx 测试配置： ```bash nginx -t ``` 重载配置： ```bash systemctl reload nginx ``` 主站日志： ```bash tail -f /www/wwwlogs/www.nomadro.cn.log tail -f /www/wwwlogs/www.nomadro.cn.error.log ``` API 日志： ```bash tail -f /www/wwwlogs/api.nomadro.cn.log tail -f /www/wwwlogs/api.nomadro.cn.error.log ``` ### 18.5 健康检查 ```bash curl -fsS http://127.0.0.1:8000/api/health curl -I http://127.0.0.1:4002/zh curl -I http://127.0.0.1:8090/api/health curl -fsS http://api.nomadro.cn/api/health curl -I https://nomadro.cn curl -I https://pocketbase.nomadro.cn/api/health ``` ### 18.6 Docker 服务 ```bash docker ps cd /opt/nomadro-services docker compose ps docker compose up -d docker compose logs -f ntfy ``` ## 19. 主要风险清单 ### P0：敏感环境文件被 Git 跟踪 `.env.local` 和 `.env.local.bak.20260606212903` 已被 Git 跟踪。`.env.example` 也包含真实样式敏感信息。 影响：密钥泄露风险。 建议：从 Git 索引移除、重置所有已暴露密钥、改 `.env.example` 为占位符、更新 `.gitignore`。 ### P0：API 子域未配置 HTTPS `api.nomadro.cn` 当前只看到 HTTP Nginx 配置。 影响：登录态、支付确认、用户资料提交等请求如果走公网 HTTP，存在明文传输风险。 建议：为 `api.nomadro.cn` 申请证书并强制 HTTP 到 HTTPS。 ### P0：默认密码 `12345678` 新用户支付后使用固定默认密码。 影响：弱口令和撞库风险。 建议：改为随机临时密码、一次性链接、强制首次设置密码。 ### P1：会员集合不一致 Next.js 使用 `site_vip`，FastAPI 使用 `memberships`。 影响：支付后不同接口可能返回不同会员状态。 建议：统一会员表或明确同步策略。 ### P1：MinIO 运行状态和代码配置不一致 代码中 Next.js 上传走 MinIO，但当前 Docker 只看到 `nomadro-ntfy`，未看到 MinIO 运行。 影响：生产上传可能失败。 建议：确认 MinIO 是否部署在其他机器/域名；如果是本机，启动并配置反代；如果不用 MinIO，统一改为 FastAPI 本地上传或其他对象存储。 ### P1：Lint 不通过 `pnpm lint` 当前 7 个 error。 影响：CI/CD、代码质量和后续维护。 建议：优先修复 lint error，再处理 warning。 ### P1：数据库与管理端口暴露面较大 MariaDB 监听 `0.0.0.0:3306`，FTP、宝塔面板、SSH 对公网开放。 影响：攻击面扩大。 建议：数据库只监听本地；管理端口限制 IP；SSH 使用密钥、禁用密码或更换端口；FTP 如非必要关闭。 ### P2：`NEXT_PUBLIC_API_BASE_URL` 必须稳定设置 `app/lib/api-client.ts` 默认值是 `http://127.0.0.1:8000`。 影响：若生产构建没有设置 `NEXT_PUBLIC_API_BASE_URL`，浏览器会访问用户本机 localhost。 建议：生产环境固定设置为 API 公网域名，且优先升级到 HTTPS。 ### P2：站点统计服务有错误日志 宝塔 `site_total` 无法写 hll 文件。 影响：宝塔统计不准确。 建议：检查目录是否存在、权限是否正确，或关闭无用统计。 ### P2：同机服务较多 同机运行 NomadCNA、PocketBase、Umami、MariaDB、PostgreSQL、Docker、Netdata、FTP、宝塔、frp-panel。 影响：故障面复杂，资源争用和安全边界不清晰。 建议：为生产服务建立清晰分层，至少将数据库/监控/管理面板访问收紧。 ## 20. 建议的下一步 ### 20.1 立即处理 1. 清理 Git 中的 `.env.local`、`.env.local.bak.*`，重置所有相关密钥。 2. 为 `api.nomadro.cn` 配置 HTTPS，并让前端 `NEXT_PUBLIC_API_BASE_URL` 使用 HTTPS。 3. 统一 VIP 数据模型，确认 `site_vip` 是否存在并补充迁移。 4. 修复 `pnpm lint` 的 7 个 error。 5. 确认 MinIO 是否实际运行；若未运行，先修复上传链路。 ### 20.2 一周内处理 1. 将默认密码机制改为随机临时密码或首次设置密码。 2. 为 `ntfy.nomadro.cn`、`netdata.nomadro.cn` 补 HTTPS，或仅内网/白名单访问。 3. 收紧 FTP、宝塔、SSH、MariaDB 的公网访问面。 4. 为 PocketBase 数据目录建立自动备份策略。 5. 添加 API smoke test，包括 `/api/health`、`/api/cities`、`/api/auth/me`、`/api/vip/check`、`/api/upload-media`。 ### 20.3 产品增强 1. 城市数据接入真实来源，增加数据更新时间和数据来源说明。 2. AI 助手接入真实模型，并基于用户画像、预算、收藏、路线生成建议。 3. 站内消息接入 ntfy / 邮件 / 企业微信。 4. 活动报名、赏金接单、服务咨询增加后台运营视图。 5. 定价页与真实支付金额、会员权益完全一致。 6. 对首页和城市卡片图片迁移到 `next/image` 或明确 CDN 图片策略。 ## 21. 当前结论 NomadCNA 当前已经完成了数字游民网站的关键骨架： - 主站可通过 `nomadro.cn` 和 `www.nomadro.cn` 访问。 - Next.js 生产服务、FastAPI、PocketBase 均在 systemd 中运行。 - Nginx 已完成主站、PocketBase、Umami 的 HTTPS 反向代理。 - FastAPI 健康接口、主站页面、PocketBase 健康接口均验证可用。 - PocketBase 已有城市、内容、活动、讨论、赏金、成员、服务、路线、通知等完整业务集合。 - 前端页面覆盖城市发现、下一站推荐、活动、匹配、工具、AI、赏金、服务、会员、报名、支付成功页和消息中心。 - `pnpm build` 已通过，说明当前生产构建可用。 同时，当前最需要优先处理的是生产安全和一致性： - 敏感环境文件不能继续被 Git 跟踪。 - API 域名需要 HTTPS。 - 会员数据模型需要统一。 - 固定默认密码需要替换。 - 上传服务需要确认实际可用。 - lint error 需要修复，以便后续稳定迭代。 整体判断：当前项目已经具备上线早期数字游民平台的基础能力，但在正式扩大用户规模前，应先完成密钥治理、HTTPS、会员模型、上传链路和 lint 修复。