Web 内容平台 · 项目总览 > 版本：v2.0 > 最后更新：2026-10-24 > 文档定位：项目全景说明，涵盖架构、模块、数据、接口、存储、响应式布局、部署与开发约定。各模块的详细实现请见对应代码与子文档。 --- ## 一、项目简介本项目是一套完整的 **Web 内容平台**（Web Content Platform），由 **三端 + 一层 Web 服务** 组成： | 端 | 角色 | 面向 | |---|---|---| | **后端 API** | FastAPI 提供服务、承载业务逻辑、文件落盘 | 前台 / 后台 | | **前台站点** | 面向访客的内容展示，动态导航、搜索、视频播放、轮播 | 公网用户（**PC + 手机**） | | **管理后台** | 内容 / 分类 / 导航 / 用户 / 轮播的可视化管理 | 运营与编辑（**PC 优先**） | | **Nginx** | 反向代理、静态资源、HTTPS、uploads 直出、SPA history | — | 内容模块：**新闻 / 博客 / 视频** 三大类，统一挂载 **分类** 体系。运营能力：**动态导航、用户管理、站内搜索、轮播位**。编辑能力：**Markdown 原生编辑器**（替代传统富文本），后台编辑、前台渲染。文件策略：所有上传 **分模块落盘**，删除记录 **连带删除对应图片/视频**。 **适配策略：前台全量响应式（PC + 移动），后台 PC 优先 + 移动端只读应急。** --- ## 二、技术栈 | 模块 | 技术选型 | |---|---| | 后端 API | Python + FastAPI + Uvicorn + SQLAlchemy + Pydantic | | 数据库 | SQLite（开发）/ MySQL 或 PostgreSQL（生产），Alembic 管理迁移 | | 鉴权 | JWT（HS256）+ bcrypt 密码哈希 | | 前台站点 | Vite + React 18 + TypeScript + React Router v6 + Axios + TailwindCSS + Swiper + ByteMD | | 管理后台 | UmiJS Max（Ant Design Pro V5）+ TypeScript + Ant Design + ProComponents + ByteMD | | Markdown | ByteMD（Editor + Viewer）+ GFM 插件 + highlight 插件 | | Web 服务 | Nginx（反代、静态、HTTPS、gzip、sendfile、SPA history） | | 进程守护 | systemd（开机自启、异常自动重启、安全加固） | | 证书 | Let's Encrypt / certbot（可自动续期） | | 响应式方案 | TailwindCSS 断点 + 自定义 `useMediaQuery` + Swiper 触摸 + ProLayout `breakpoint` | --- ## 三、系统架构 ``` ┌──────────────────────────────────────┐ │ Nginx (443/80) │ │ HTTPS · gzip · sendfile · history │ └──────┬──────────────┬──────────┬─────┘ │ │ │ /api/* 反代 │ / 静态 │ /admin │ /uploads 直出 ▼ ▼ ▼ ┌────────────┐ ┌──────────┐ ┌──────────────┐ │ FastAPI │ │ 前台 dist │ │ /var/www/ │ │ 127.0.0.1 │ │ (Vite) │ │ uploads/ │ │ :8000 │ └──────────┘ └──────────────┘ │ systemd │ ┌──────────┐ │ 守护 │ │ 后台 dist │ └─────┬──────┘ │ (Umi) │ │ └──────────┘ ▼ ┌────────────┐ │ 数据库 │ │ SQLite/MySQL│ └────────────┘ ``` **核心原则：** - 三端通过统一的 `/api` 契约松耦合，任一模块可独立演进。 - 上传文件 **不经过 FastAPI 二次读盘**，由 Nginx `alias` 直出。 - 后台所有写操作需鉴权（`require_admin`），读接口面向公众开放。 - 前台布局 **移动优先（mobile-first）**，向上适配到桌面；后台布局 **桌面优先**，移动端保底可用。 --- ## 四、目录结构 ``` web/ ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── main.py # 应用入口，注册所有 router │ │ ├── config.py # 全局配置、上传白名单 │ │ ├── database.py # SQLAlchemy engine / Base / get_db │ │ ├── deps.py # get_current_user / require_admin │ │ ├── models/ │ │ │ ├── user.py │ │ │ ├── navigation.py │ │ │ ├── banner.py │ │ │ ├── category.py │ │ │ ├── news.py │ │ │ ├── blog.py │ │ │ └── video.py │ │ ├── schemas/ # Pydantic 出入参 │ │ ├── routers/ │ │ │ ├── auth.py │ │ │ ├── users.py # 用户管理 │ │ │ ├── navigations.py # 动态导航 │ │ │ ├── banners.py # 轮播 │ │ │ ├── categories.py │ │ │ ├── news.py │ │ │ ├── blogs.py │ │ │ ├── videos.py │ │ │ ├── search.py # 站内搜索 │ │ │ └── upload.py # 统一上传 │ │ └── utils/ │ │ ├── security.py # JWT / bcrypt │ │ └── files.py # 落盘 + 连带删除（支持 HTML/Markdown 双格式） │ ├── uploads/ # Nginx 直出（不纳入版本控制） │ │ ├── news/YYYY/MM/DD/ │ │ ├── blogs/YYYY/MM/DD/ │ │ ├── covers/YYYY/MM/DD/ │ │ ├── videos/YYYY/MM/DD/ │ │ ├── avatars/YYYY/MM/DD/ │ │ ├── nav/YYYY/MM/DD/ │ │ └── banners/YYYY/MM/DD/ │ ├── alembic/ # 数据库迁移 │ ├── requirements.txt │ └── .env │ ├── frontend/ # Vite + React + TS（前台，全量响应式） │ └── src/ │ ├── api/request.ts # axios 封装 │ ├── hooks/ │ │ ├── useNavigation.ts # 动态导航 │ │ ├── useBanners.ts # 轮播数据 │ │ └── useMediaQuery.ts # 响应式断点监听 │ ├── components/ │ │ ├── Navbar.tsx # 响应式导航（PC 下拉 + 移动抽屉） │ │ ├── BannerCarousel.tsx # 轮播组件（Swiper，高度自适应） │ │ ├── MarkdownViewer.tsx # Markdown 渲染（ByteMD Viewer） │ │ └── ... │ ├── pages/ │ │ ├── Home.tsx │ │ ├── Search.tsx # 站内搜索页 │ │ ├── News/ Blog/ Video/ # 三大内容模块 │ │ └── ... │ └── styles/markdown.css # 正文排版与溢出防护 │ ├── admin/ # Umi Antd Pro V5（后台，PC 优先） │ └── src/ │ ├── components/MarkdownEditor.tsx # Markdown 编辑器（ByteMD Editor） │ └── pages/ │ ├── User/index.tsx │ ├── Navigation/index.tsx │ ├── Banner/index.tsx │ ├── Category/index.tsx │ ├── News/ Blog/ Video/ # 内容管理 │ └── ... │ └── deploy/ ├── nginx/web.conf ├── systemd/web-api.service └── scripts/ # 备份、证书续期等 ``` --- ## 五、功能模块总览 ### 5.1 内容模块（新闻 / 博客 / 视频）三大内容模块共享统一的字段模型与管理语义： | 能力 | 说明 | |---|---| | 增删改查 | 后台 ProTable + 表单 | | 分类归属 | 多对一关联 `category_id` | | 上下架 | `is_published` 字段，前台只展示已上架 | | 置顶 | `is_top` 字段，列表按 `is_top DESC, published_at DESC` 排序 | | 封面 / 附件 | `cover` / `video` 字段，走统一上传 | | 正文格式 | **Markdown 原文**（`content` 字段存纯文本 Markdown），后台 ByteMD 编辑、前台 ByteMD 渲染 | | 列表分页 | `page` / `size` 参数 | | 详情页 | 按 `id` 查询，含分类信息 | **视频模块额外能力：** - 独立视频文件 `video` 字段，支持 Range 断点续传（Nginx 直出） - 前台详情页内嵌 `

{title}