基于云开发 + CloudBase AI ToolKit 构建的社交平台项目

乡愁 是一个基于 React + 腾讯云 CloudBase 的全栈社交应用。用户可以分享生活动态、浏览发现内容、关注互动、即时聊天以及购物。项目采用现代化前端技术栈，结合 CloudBase 提供的认证、数据库、云函数和云存储等后端服务能力，实现免服务器全栈开发。

• 社区动态 - 浏览信息流、发布笔记/帖子、点赞评论、收藏分享
• 社交互动 - 关注/粉丝系统、即时聊天、消息通知
• 用户中心 - 个人资料编辑、我的帖子管理、收藏夹
• 搜索发现 - 热门搜索、搜索历史、用户搜索、内容搜索
• 乡里板块 - 本地化内容展示（Xiangli 页面）
• 商城购物 - 商品浏览、购物车（Cart）
• 用户认证 - 用户名密码登录/注册、匿名登录、手机号验证码登录（独立 auth 模块）

xiangchou/
├── xiangguanguli/              # 主应用（前端 + 云函数）
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/     # React 组件（Layout、TabBar、UI 组件库）
│   │   │   ├── context/        # 全局状态管理 (AppContext)
│   │   │   ├── hooks/          # 自定义 Hooks
│   │   │   ├── pages/          # 页面组件
│   │   │   └── App.tsx         # 应用入口 & 路由配置
│   │   ├── lib/
│   │   │   ├── cloudbase.ts    # CloudBase SDK 初始化
│   │   │   ├── auth.ts         # 认证工具函数
│   │   │   └── db-utils.ts     # 数据库工具
│   │   ├── styles/             # 样式文件（Tailwind、主题、字体）
│   │   └── main.tsx            # 应用启动
│   ├── cloudfunctions/         # 云函数（26 个）
│   │   ├── init-db/            #   数据库初始化
│   │   ├── getOpenId/          #   获取 OpenID
│   │   ├── publishNote/        #   发布笔记
│   │   ├── getNotes/           #   获取笔记列表
│   │   ├── createPost/         #   创建帖子
│   │   ├── getPosts/           #   获取帖子列表
│   │   ├── deletePost/         #   删除帖子
│   │   ├── likeNote/           #   点赞笔记
│   │   ├── toggleLike/         #   切换点赞
│   │   ├── toggleFavorite/     #   切换收藏
│   │   ├── getFavorites/       #   获取收藏列表
│   │   ├── createComment/      #   创建评论
│   │   ├── deleteComment/      #   删除评论
│   │   ├── getComments/        #   获取评论列表
│   │   ├── toggleFollow/       #   切换关注
│   │   ├── getFollowers/       #   获取粉丝列表
│   │   ├── getFollowing/       #   获取关注列表
│   │   ├── getProfile/         #   获取用户资料
│   │   ├── updateProfile/      #   更新用户资料
│   │   ├── searchPosts/        #   搜索帖子
│   │   ├── searchUsers/        #   搜索用户
│   │   ├── getHotSearch/       #   获取热门搜索
│   │   ├── getSearchHistory/   #   获取搜索历史
│   │   ├── sendMessage/        #   发送消息
│   │   ├── getMessages/        #   获取消息列表
│   │   ├── getChatMessages/    #   获取聊天记录
│   │   ├── getOrCreateChat/    #   获取或创建会话
│   │   ├── markMessagesAsRead/ #   标记消息已读
│   │   ├── createOrder/        #   创建订单
│   │   ├── getGoods/           #   获取商品列表
│   │   ├── uploadImage/        #   上传图片
│   │   └── collectNote/        #   收集笔记
│   ├── Dockerfile              # Docker 镜像配置
│   ├── docker-compose.yml      # Docker Compose 编排
│   ├── nginx.conf              # Nginx 配置
│   ├── cloudbaserc.json        # CloudBase 配置
│   ├── vite.config.ts          # Vite 构建配置
│   ├── package.json            # 项目依赖
│   └── env.example             # 环境变量模板
├── auth/                       # 独立认证模块（手机号登录）
│   ├── config.js               # CloudBase 配置
│   ├── auth.js                 # Auth SDK 封装
│   ├── register.html/js        # 注册页面
│   ├── login.html/js           # 登录页面
│   ├── index.html              # 用户中心
│   └── styles.css              # 样式
├── rules/                      # AI 编程规则集（CloudBase AI ToolKit）
├── cloudbaserc.json            # 仓库级 CloudBase 配置
├── Assistant.md                # CNB NPC 配置
└── README.md                   # 本文件

技术	版本	说明
React	18.3.1	UI 框架
TypeScript	-	类型安全
Vite	6.3.5	构建工具
React Router	7.12.0	路由管理
Tailwind CSS	4.1.12	样式框架
Radix UI	-	无障碍 UI 组件库
MUI	7.3.5	Material Design 组件
Lucide React	0.487.0	图标库
Motion	12.23.24	动画库
React Hook Form	7.55.0	表单管理
Recharts	2.15.2	图表库
Sonner	2.0.3	Toast 消息提示

服务	说明
CloudBase Web SDK 2.25.1	云开发 SDK
Auth v3	身份认证（用户名密码/匿名/手机号）
NoSQL 文档数据库	数据存储（users、posts、messages 等集合）
云函数 (26 个)	业务逻辑（发布、评论、关注、搜索、聊天等）
云存储	文件上传下载（头像、图片等）
静态网站托管	前端部署

方式	说明
CloudBase 静态托管	一键部署到腾讯云
Docker + Nginx	容器化部署（含 docker-compose）

• Node.js 18+
• npm 或 pnpm
• CloudBase 环境（腾讯云）

git clone https://cnb.cool/oiool/xiangchou.git
cd xiangchou

cd xiangguanguli
npm install

cp env.example .env.local

编辑 .env.local，填入实际的 CloudBase 配置：

VITE_CLOUDBASE_ENV_ID=你的环境ID
VITE_CLOUDBASE_REGION=ap-shanghai
VITE_CLOUDBASE_PUBLISHABLE_KEY=你的PublishableKey

Publishable Key 可在 CloudBase 控制台 > API 密钥 获取。

npm run dev

访问 http://localhost:5173 查看应用。

npm run build

构建输出在 dist/ 目录。

# 安装 CloudBase CLI
npm install -g @cloudbase/cli

# 登录
tcb login

# 部署
tcb hosting:deploy dist -e hjhsite-4gwrqvh455f57d20

# 构建镜像
docker build -t xiangguanguli .

# 运行容器
docker run -d -p 80:80 \
  -e VITE_CLOUDBASE_PUBLISHABLE_KEY=你的key \
  xiangguanguli

或使用 Docker Compose：

# 编辑 .env 文件设置环境变量
cp env.docker.example .env

# 启动
docker-compose up -d

配置项	值
环境 ID	hjhsite-4gwrqvh455f57d20
环境别名	hjhsite
区域	ap-shanghai（上海）
云函数根目录	./cloudfunctions

• 环境概览
• 文档数据库
• 云函数
• 云存储
• 身份认证
• 静态网站托管

建议在 身份认证管理 中：

• 必须开启：用户名密码登录（UserNameLogin）
• 可选开启：匿名登录（AnonymousLogin，用于游客模式）
• 可选开启：短信登录（SmsLogin，需配置短信模板）

路径	页面	是否需要登录
/	首页（信息流）	否
/xiangli	乡里板块	否
/post/:postId	帖子详情	否
/user/:userId	用户主页	否
/user/:userId/notes	用户笔记	否
/user/:userId/followers	粉丝列表	否
/user/:userId/following	关注列表	否
/search	搜索结果	否
/search/users	用户搜索	否
/login	登录	否
/profile	个人中心	是
/create	发布内容	是
/messages	消息列表	是
/chat/:chatId	聊天详情	是
/settings	编辑资料	是
/my-posts	我的帖子	是
/following	我的关注	是
/followers	我的粉丝	是
/favorites	收藏夹	是
/cart	购物车	是

1. 认证方式：必须使用 CloudBase Web SDK 内置认证，禁止在云函数中实现明文密码校验
2. 写操作：前端不直写数据库/不直传云存储，所有写操作统一通过云函数（便于鉴权、校验与审计）
3. 读操作：简单查询可直连数据库，复杂聚合/状态判断建议走云函数
4. 错误处理：所有 CloudBase API 调用需包含完整错误处理

• TypeScript 进行类型检查
• 函数式组件 + React Hooks
• Tailwind CSS 编写样式
• Radix UI / MUI 组件库

本项目基于 Figma 设计 实现。

---

项目维护者: 如有问题或建议，请通过 Issue 反馈。

本项目基于 CloudBase AI ToolKit 开发，通过 AI 提示词和 MCP 协议 + 云开发，让开发更智能、更高效。

Q: 什么是"香臭"？ A: 本仓库名称来源于项目代号，详情请咨询项目负责人。

Q: 如何参与开发？ A: Fork 本仓库，创建功能分支，完成后提交 Pull Request。