jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3 Commits
1 Branch
0 Tags
2.6 MiB
 
Branch: main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
docs/v1.0/architecture/tech-stack.md

5.3 KiB
Raw Permalink Blame History

项目技术栈架构文档

更新时间：2026-01-21
部署方式：Docker Compose

📋 目录

🎨 前端技术栈

核心框架

  • React 19.2.0 - UI 框架
  • TypeScript 5.9.3 - 类型系统
  • Vite 7.2.4 - 构建工具

路由与状态管理

  • React Router DOM 7.6.1 - 客户端路由
  • Zustand 5.0.5 - 轻量级状态管理
  • TanStack Query 5.80.7 - 服务端状态管理与数据缓存

UI 组件库

  • Radix UI - 无样式可访问组件库
    • Dialog, Dropdown, Popover, Tooltip 等 20+ 组件
  • Lucide React 0.562.0 - 图标库
  • Tailwind CSS 4.1.18 - 原子化 CSS 框架
  • Tailwind Animate - 动画工具

表单与验证

  • React Hook Form 7.57.0 - 表单管理
  • Zod 3.25.64 - Schema 验证
  • @hookform/resolvers 5.1.0 - 表单验证集成

拖拽与交互

  • @dnd-kit - 拖拽排序
    • core 6.3.1
    • sortable 10.0.0
    • utilities 3.2.2

文档处理

  • Fountain.js 1.2.4 - 剧本格式解析
  • Mammoth 1.11.0 - Word 文档解析
  • PDF.js 5.4.530 - PDF 渲染
  • Turndown 7.2.2 - HTML 转 Markdown
  • React Markdown 10.1.0 - Markdown 渲染

国际化

  • i18next 25.2.1 - 国际化框架
  • react-i18next 15.5.2 - React 集成
  • i18next-browser-languagedetector - 语言检测
  • i18next-http-backend - 远程翻译加载

工具库

  • Axios 1.10.0 - HTTP 客户端
  • date-fns 4.1.0 - 日期处理
  • clsx + tailwind-merge - 类名合并
  • class-variance-authority - 组件变体管理

虚拟化

  • react-window 2.2.5 - 列表虚拟化
  • react-virtualized-auto-sizer - 自动尺寸计算

⚙️ 后端技术栈

核心框架

  • FastAPI 0.109.0 - 现代异步 Web 框架
  • Uvicorn 0.27.0 - ASGI 服务器（支持 HTTP/2）
  • Python 3.11+ - 编程语言

ORM 与数据库

  • SQLModel 0.0.14 - SQL ORM（基于 Pydantic + SQLAlchemy）
  • Alembic 1.13.1 - 数据库迁移工具
  • asyncpg 0.29.0 - PostgreSQL 异步驱动

缓存

  • Redis 5.0.1 - 内存数据库
  • hiredis 2.3.2 - Redis 高性能 C 解析器

认证与安全

  • python-jose[cryptography] 3.3.0 - JWT 令牌
  • passlib[bcrypt] 1.7.4 - 密码哈希

配置管理

  • pydantic-settings 2.1.0 - 配置管理
  • python-dotenv 1.0.0 - 环境变量加载

工具库

  • loguru 0.7.2 - 日志系统
  • python-dateutil 2.8.2 - 日期处理
  • pytz 2023.3 - 时区处理
  • uuid-utils 0.9.0 - UUID 工具
  • pypinyin 0.51.0 - 中文转拼音

开发工具

  • pytest 7.4.4 - 测试框架
  • pytest-asyncio 0.23.3 - 异步测试支持
  • httpx 0.26.0 - 异步 HTTP 客户端
  • black 24.1.1 - 代码格式化
  • ruff 0.1.14 - 快速 Linter

🐳 基础设施

容器化

  • Docker - 容器运行时
  • Docker Compose - 多容器编排

数据库

  • PostgreSQL 17 Alpine - 主数据库
    • 端口：6181
    • 支持 UUID v7

缓存

  • Redis 7 Alpine - 缓存与会话存储
    • 端口：6183

对象存储

  • S3 兼容存储 - 使用 boto3 SDK
    • 生产环境：阿里云 OSS
    • 开发环境：可选 AWS S3、MinIO 等
    • 支持所有 S3 兼容存储服务

网络

  • jointo-network - Docker Bridge 网络
  • CORS 配置 - 支持跨域请求

🛠️ 开发工具

前端开发

  • ESLint 9.39.2 - 代码检查
  • Prettier 3.7.4 - 代码格式化
  • Husky 9.1.7 - Git Hooks
  • lint-staged 16.2.7 - 暂存文件检查

后端开发

  • Black - Python 代码格式化
  • Ruff - Python Linter
  • pytest - 单元测试

构建与部署

  • Vite - 前端构建（开发端口：6160）
  • Uvicorn - 后端服务（端口：6170）
  • Docker Multi-stage Build - 生产环境构建

📊 端口分配

服务 端口 说明
前端开发服务 6160 Vite Dev Server
后端 API 6170 FastAPI Application
PostgreSQL 6181 数据库
Redis 6183 缓存
Adminer 6184 数据库管理工具

🔄 数据流架构

┌─────────────┐
│   Browser   │
│  (React)    │
└──────┬──────┘
       │ HTTP/REST
       ↓
┌─────────────┐      ┌──────────┐
│  FastAPI    │─────→│  Redis   │
│  (Uvicorn)  │      │  (Cache) │
└──────┬──────┘      └──────────┘
       │
       ↓
┌─────────────┐      ┌──────────────┐
│ PostgreSQL  │      │ S3 Storage   │
│  (Primary)  │      │ (OSS/S3/etc) │
└─────────────┘      └──────────────┘

📝 备注

  • 所有服务通过 Docker Compose 统一管理
  • 前端使用 Vite 进行开发和构建
  • 后端采用异步架构（asyncpg + FastAPI）
  • 数据库使用 PostgreSQL 17 最新特性
  • 对象存储使用 boto3 SDK，支持所有 S3 兼容存储（阿里云 OSS、AWS S3 等）