# FengAdmin **Repository Path**: ksufer/FengAdmin ## Basic Information - **Project Name**: FengAdmin - **Description**: 基于 React + Flask 的现代化全栈个人生产力管理平台，集成待办事项、AI助手、笔记管理、GitHub趋势等功能，支持 Docker 部署和明暗主题切换。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-10-10 - **Last Updated**: 2025-10-17 ## Categories & Tags **Categories**: backend **Tags**: None ## README # 🎯 Feng Admin - Monorepo 项目 一个基于 React + Flask 的现代化全栈个人生产力管理平台，采用 monorepo 架构组织。 > **🚀 第一次使用？** 查看 [快速上手指南](./docs/setup/getting-started.md) - 5分钟内启动项目！ > > **✨ 完全自动化** - 无需手动创建虚拟环境，启动脚本会自动处理一切！ ![界面](image.png "界面") ## 📂 项目结构 ``` Feng_Admin/ ├── apps/ # 应用程序 │ ├── frontend/ # React 前端应用 │ │ ├── src/ │ │ │ ├── components/ # UI 组件 │ │ │ ├── contexts/ # React Context │ │ │ ├── layouts/ # 布局组件 │ │ │ ├── lib/ # 工具函数 │ │ │ └── pages/ # 页面组件 │ │ ├── package.json │ │ └── vite.config.ts │ │ │ └── backend/ # Flask 后端 API │ ├── routes/ # API 路由 │ ├── instance/ # 数据库文件 │ ├── cache/ # 缓存文件 │ ├── app.py # 主应用 │ ├── models.py # 数据模型 │ ├── config.py # 配置 │ └── requirements.txt │ ├── tools/ # 工具脚本 │ └── github_trending_scraper/ # GitHub 趋势爬虫 │ ├── docs/ # 项目文档 │ ├── QUICKSTART.md # 快速开始 │ ├── USER_GUIDE.md # 使用指南 │ └── CHANGELOG.md # 更新日志 │ ├── package.json # 根工作区配置 ├── pnpm-workspace.yaml # pnpm 工作区配置 ├── start.bat # Windows 一键启动脚本 └── start.sh # Linux/macOS 一键启动脚本 ``` ## ✨ 核心功能 ### 基础功能 - 🔐 **用户认证**：JWT Token 认证，支持注册/登录/自动刷新 - 📧 **邮件系统**：多邮箱管理、邮件收发、文件夹浏览、搜索功能 - 📝 **待办事项**：任务管理，支持 CRUD、分页、筛选、排序 - 🤖 **智能体管理**：动态配置 AI 助手，支持导入/导出 - 📄 **Markdown 笔记**：实时编辑和预览，支持多用户隔离 - 🔥 **GitHub 趋势**：查看热门开源项目，支持多语言筛选 - 📊 **Excel 查看器**：在线上传、解析、查看 Excel 文件 - 🎨 **主题切换**：明亮/暗黑/跟随系统 - 🛠️ **实用工具**：JSON 格式化、AI Playground - 💬 **AI Playground**：多提供商支持，会话管理和历史记录 - 🕷️ **网页爬虫**：简单的 URL 抓取功能 ### 高级特性 - 🎛️ **功能开关**：前后端独立的功能模块开关（Feature Flags） - 🔒 **RBAC 权限系统**：基于角色的访问控制 - 🐳 **Docker 支持**：完整的 Docker 和 docker-compose 配置 - 🧪 **测试支持**：前端 Vitest + 后端 Pytest 测试框架 - ⚡ **优化体验**：前端乐观更新、加载状态、错误处理 - 🌍 **国内源支持**：Docker 构建支持国内镜像源（pip/npm/apt） ## 🔐 重要：API Key 配置 **本项目不包含任何真实的 API Key！** 为了安全考虑，所有 API Key 需要您自己配置。 ### 快速配置步骤： 1. **启动应用后，进入"设置"页面** 2. **找到"AI 提供商配置"部分** 3. **选择一个提供商并配置 API Key：** - 🇨🇳 **阿里云百炼**（推荐）：https://dashscope.console.aliyun.com/apiKey - 💻 **DeepSeek**：https://platform.deepseek.com/api_keys - 🏠 **Ollama**（本地免费）：https://ollama.com/download 4. **保存配置并测试** 📖 **详细说明：** [API Key 配置与安全使用指南](./docs/guides/api-key-guide.md) ### 安全特性： - ✅ API Key 仅存储在您的浏览器本地 - ✅ 不会上传到任何服务器 - ✅ 代码仓库不包含真实密钥 - ✅ 已添加 `.gitignore` 保护 ## 🚀 快速开始 ### 方式一：本地开发（推荐新手） #### 环境要求 - Node.js 18+ - Python 3.8+ #### 一键启动 启动脚本会自动完成以下操作： - ✅ 检查环境 - ✅ 检查并引导配置环境变量 - ✅ 创建 Python 虚拟环境 - ✅ 安装依赖 - ✅ 启动服务 #### Windows ```bash # 双击运行或在命令行执行 start.bat ``` #### Linux / macOS ```bash # 添加执行权限（首次运行） chmod +x start.sh # 运行启动脚本 ./start.sh ``` **注意**：启动脚本会自动创建 `.venv` 虚拟环境，无需手动创建。 #### 手动启动 如果需要手动启动，请按以下步骤： ```bash # 0. 创建虚拟环境（首次运行） python -m venv .venv # 1. 安装依赖 npm run install:frontend npm run install:backend # 2. 启动后端（端口 5001） npm run start:backend:win # Windows npm run start:backend # Linux/macOS # 3. 启动前端（端口 5173） npm run dev ``` 访问 `http://localhost:5173` 即可使用。 --- ### 方式二：Docker 部署（推荐生产环境） #### 环境要求 - Docker 20.10+ - Docker Compose 2.0+ #### 快速启动 ```bash # 1. 克隆项目 git clone Feng_Admin cd Feng_Admin # 2. 配置环境变量（可选） cp env.example .env # 编辑 .env 文件，配置 SECRET_KEY 和 JWT_SECRET_KEY # 3. 使用 Docker Compose 启动 docker-compose up -d # 查看日志 docker-compose logs -f # 停止服务 docker-compose down ``` 访问 `http://localhost:5173` 即可使用。 **详细说明：** [Docker 部署指南](./docs/guides/docker-guide.md) #### Docker 国内镜像源 为了加速 Docker 构建，项目已配置国内镜像源： - **Python 依赖**：清华 TUNA PyPI 镜像 - **Node 依赖**：npmmirror 镜像 - **APT 包**：清华 TUNA Debian 镜像 可以通过环境变量自定义镜像源： ```bash # 在 .env 文件中设置 PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple PIP_TRUSTED_HOST=mirrors.aliyun.com NPM_REGISTRY=https://registry.npmmirror.com APT_MIRROR=mirrors.tuna.tsinghua.edu.cn ``` ### 🌐 远程访问 应用已配置为支持远程访问，可以在局域网内的其他设备访问： ```bash # 查看服务器 IP 地址 ipconfig # Windows ifconfig # Linux/macOS # 在其他设备访问 http://服务器IP:5173 # 前端 http://服务器IP:5001 # 后端 API ``` **📖 详细指南**：[远程访问配置指南](./docs/guides/remote-access.md) **包含内容**： - ✅ 防火墙配置 - ✅ CORS 跨域设置 - ✅ 生产环境安全建议 - ✅ 反向代理配置 - ✅ 常见问题解答 ## 📚 文档 ### 🚀 新手入门 - **[快速开始指南](./docs/setup/getting-started.md)** ⭐ - 5分钟快速上手 - [Linux/macOS 支持](./docs/setup/linux-support.md) - Linux 和 macOS 用户指南 - [Docker 部署指南](./docs/guides/docker-guide.md) 🐳 - 使用 Docker 快速部署 ### ⚙️ 环境配置 - **[环境配置指南](./docs/setup/environment-setup.md)** - 本地/远程/生产环境配置 - [端口和域名配置](./docs/setup/port-and-domain-config.md) - 端口占用/域名配置解决方案 - [脚本使用指南](./docs/guides/scripts-guide.md) - 启动和配置脚本说明 - [功能开关指南](./docs/guides/feature-flags.md) 🎛️ - 模块化功能控制 ### 📖 用户文档 - [功能使用指南](./docs/guides/user-guide.md) - 各功能的详细使用方法 - [API Key 配置](./docs/guides/api-key-guide.md) - AI 功能配置和安全使用 - [远程访问指南](./docs/guides/remote-access.md) - 局域网/外网访问配置 - [RBAC 权限指南](./docs/guides/rbac-guide.md) 🔒 - 角色权限管理 - [更新日志](./docs/project/changelog.md) - 版本更新记录 ### 🛠️ 开发文档 - **[AI 开发提示词](./docs/guides/ai-prompt-quick-reference.md)** 🤖 - 在其他 AI 环境快速开发功能 - [AI 提示词完整版](./docs/guides/ai-development-prompt.md) - 完整的 AI 协作开发规范 - [AI 提示词使用示例](./docs/guides/ai-prompt-example-usage.md) - 实际使用案例 - [新建页面完整指南](./docs/guides/add-new-page.md) - 详细教程和案例 - [页面模板系统](./templates/page-template/README.md) - 5分钟快速创建页面 - [模板快速指南](./templates/page-template/QUICK_START_GUIDE.md) - 模板使用说明 - [测试指南](./docs/guides/testing-guide.md) 🧪 - Vitest 和 Pytest 测试 - **[多仓库推送脚本](./docs/guides/git-push-multiple-repos.md)** 📤 - 同时推送到 GitHub 和 Gitee ### 🚀 部署运维 - [生产环境部署](./docs/guides/deployment.md) - 完整部署流程 - [Docker 部署指南](./docs/guides/docker-guide.md) 🐳 - Docker 容器化部署 ## 🏗️ Monorepo 架构 本项目采用 monorepo 架构，具有以下优势： - ✅ **统一管理**：前后端代码在同一仓库，便于协作 - ✅ **清晰结构**：`apps/` 存放应用，`tools/` 存放工具 - ✅ **共享配置**：根目录统一管理脚本和配置 - ✅ **版本控制**：统一的 Git 历史和版本管理 - ✅ **易于扩展**：可轻松添加新应用或共享包 ## 🛠️ 技术栈 ### 前端 (apps/frontend) - **框架**：React 19 + TypeScript - **构建工具**：Vite 7 - **路由**：React Router 7 - **UI**：Tailwind CSS + shadcn/ui - **状态管理**：React Context - **测试**：Vitest + @testing-library/react - **容器化**：Docker + Nginx ### 后端 (apps/backend) - **框架**：Flask + Flask-CORS - **数据库**：SQLite + SQLAlchemy（支持 PostgreSQL/MySQL） - **认证**：JWT + bcrypt - **权限**：基于角色的访问控制（RBAC） - **爬虫**：Beautiful Soup 4 - **测试**：Pytest - **容器化**：Docker + Gunicorn ### DevOps - **容器化**：Docker + Docker Compose - **反向代理**：Nginx - **进程管理**：Gunicorn（生产环境） - **CI/CD**：支持 GitHub Actions（可扩展） ## 📦 工作区脚本 ```bash # 前端相关 npm run dev # 启动前端开发服务器 npm run build # 构建前端生产版本 npm run lint # 运行前端代码检查 npm run install:frontend # 安装前端依赖 # 后端相关 npm run start:backend # 启动后端服务 npm run install:backend # 安装后端依赖 ``` ## 🔐 默认测试账号 运行 `python apps/backend/migrate_data.py` 创建测试用户： - 邮箱：`admin@example.com` - 密码：`admin123` ## 📝 开发指南 ### 添加新功能 1. 前端：在 `apps/frontend/src/pages/` 添加新页面 2. 后端：在 `apps/backend/routes/` 添加新路由 3. 数据库：在 `apps/backend/models.py` 添加模型 ### 数据库位置 - 数据库文件：`apps/backend/instance/feng_admin.db` - 缓存文件：`apps/backend/cache/` ## 🤝 贡献 欢迎为项目做贡献！请查看 [贡献指南](./CONTRIBUTING.md) 了解详细信息： - 📖 [贡献指南](./CONTRIBUTING.md) - 如何参与项目开发 - 📚 [文档中心](./docs/README.md) - 完整文档索引 - 🐛 [提交 Issue](https://github.com/YOUR_PROJECT/Feng_Admin/issues) - 💬 [参与讨论](https://github.com/YOUR_PROJECT/Feng_Admin/discussions) ## 📄 许可证 MIT License ## 🔗 相关链接 - **文档** - [📖 文档中心](./docs/README.md) - 所有文档的导航索引 - [🚀 快速上手](./docs/setup/getting-started.md) - 新手入门指南 - [📘 用户指南](./docs/guides/user-guide.md) - 功能使用说明 - [🚢 部署指南](./docs/guides/deployment.md) - 生产环境部署 - **开发** - [🤝 贡献指南](./CONTRIBUTING.md) - 参与开发 - [📝 更新日志](./docs/project/changelog.md) - 版本历史 - [🔧 环境配置](./docs/setup/environment-setup.md) - 环境变量 - **项目信息** - 版本：v1.0.0 - 最后更新：2025-10-10 - 许可证：MIT License --- **需要帮助？** 查看 [文档中心](./docs/README.md) 或 [提交 Issue](https://github.com/YOUR_PROJECT/Feng_Admin/issues)