439 lines
18 KiB
Markdown
439 lines
18 KiB
Markdown
# 极码 GeekCode
|
||
|
||
集开发者社区、AI 工具库和经验知识库为一体的综合平台，为程序员提供 AI 驱动的需求分析、架构选型、智能排版、联网搜索等工具，同时支持经验分享、API 管理、导航站等社区功能。
|
||
|
||
## 功能特性
|
||
|
||
### 1. 经验知识库（帖子系统）
|
||
- **功能说明**：用户发布技术经验帖，支持 Markdown 编辑、分类标签、点赞收藏评论、草稿保存
|
||
- **实现方式**：`backend/routers/posts.py` 提供完整 CRUD API，支持信息流（关注/热门/最新）三种排序，自动提取首张图片作为封面（`_extract_cover_image`），热门排序算法为 `like_count * 3 + comment_count * 2 + view_count`
|
||
- **优点**：程序员可沉淀技术经验，形成团队知识资产
|
||
|
||
### 2. AI 智能排版
|
||
- **功能说明**：一键将文章重新排版为结构清晰的 Markdown 格式，可选自动生成配图
|
||
- **实现方式**：`backend/routers/ai_format.py` 调用 reasoning 类型 AI 模型排版，支持 Seedream 5.0 生成配图并上传 COS 永久存储，自动过滤 `<think>` 思考过程
|
||
- **优点**：保持原文不变只改格式，大幅提升文章可读性
|
||
|
||
### 3. 需求理解助手
|
||
- **功能说明**：将甲方原始需求（口语、截图、文档）转化为结构化需求文档
|
||
- **实现方式**：`backend/routers/requirement.py` 使用多模态 AI 模型，支持图片上传分析，流式输出 SSE，输出包含 MECE 功能拆解、用户故事、验收标准、复杂度预警
|
||
- **优点**：兼具产品经理和程序员双重视角，直接产出可开发的需求文档
|
||
|
||
### 4. 架构选型助手
|
||
- **功能说明**：根据功能需求输出完整技术方案，包含技术选型对比、架构图、数据模型、开发路线图
|
||
- **实现方式**：`backend/routers/architecture.py` 流式输出，包含 Mermaid 架构图、ER 图、API 清单、工期评估
|
||
- **优点**：基于实战经验推荐最合适的技术栈，避免过度设计
|
||
|
||
### 5. 联网搜索
|
||
- **功能说明**：基于火山方舟豆包大模型的联网搜索工具，获取最新信息
|
||
- **实现方式**：`backend/routers/web_search.py` 调用火山方舟 API 的 `web_search` 工具，搜索结果条数可配置（1-50 条），流式输出，保存对话历史
|
||
- **优点**：获取实时信息，搜索结果经 AI 整合总结
|
||
|
||
### 6. 团队知识库
|
||
- **功能说明**：从经验帖中精选内容构建团队知识库，支持分类和密码保护
|
||
- **实现方式**：`backend/routers/knowledge_base.py` 管理员从帖子中选择添加，支持分类管理、排序、摘要生成，独立密码认证（`X-Kb-Token`）
|
||
- **优点**：沉淀高质量内容，控制知识库访问权限
|
||
|
||
### 7. API Hub（共享 API 管理）
|
||
- **功能说明**：团队 API 端点管理平台，支持分类、加密存储 API Key、健康检查、调用日志
|
||
- **实现方式**：`backend/routers/shared_api.py` 提供完整管理功能，API Key 加密存储，支持 4 种认证方式（none/api_key/bearer/basic），独立密码认证（`X-Hub-Token`）
|
||
- **优点**：团队共享 API 资源，自动监控 API 可用性
|
||
|
||
### 8. 导航站
|
||
- **功能说明**：开发者常用网站导航，支持用户提交和管理员审核
|
||
- **实现方式**：`backend/routers/nav.py` 提供分类管理、链接管理、用户提交审核流程（pending → approved/rejected）
|
||
- **优点**：UGC 模式丰富导航内容，审核机制保证质量
|
||
|
||
### 9. 开源项目收藏
|
||
- **功能说明**：GitHub 开源项目浏览和收藏，支持实时搜索 GitHub
|
||
- **实现方式**：`backend/routers/projects.py` 集成 GitHub API 实时搜索，管理员可批量导入，用户可收藏项目
|
||
- **优点**：一站式发现和管理开源项目
|
||
|
||
### 10. 用户头像上传
|
||
- **功能说明**：用户可上传自定义头像，存储到腾讯云 COS
|
||
- **实现方式**：前端 `Profile.vue` 点击头像触发上传，调用 `uploadApi.uploadImage` 上传到 COS，再通过 `authApi.updateProfile` 保存头像 URL
|
||
- **优点**：个性化用户形象，对象存储保证访问速度
|
||
|
||
### 11. 多 AI 模型管理
|
||
- **功能说明**：后台可视化配置多个 AI 服务商和模型，按任务类型分配
|
||
- **实现方式**：`backend/routers/ai_models.py` 支持 5 大服务商预置模型（DeepSeek、OpenAI、Anthropic、Google Gemini、火山方舟），6 种任务类型，支持测试连接
|
||
- **优点**：灵活切换模型，按场景选择最合适的 AI 能力
|
||
|
||
### 12. 用户系统
|
||
- **功能说明**：注册登录、个人资料、关注粉丝、消息通知
|
||
- **实现方式**：JWT 认证（7 天有效期），新用户注册需管理员审核，支持封禁/解禁，实时通知（点赞、评论、关注）
|
||
- **优点**：审核机制保证社区质量
|
||
|
||
### 13. 后台管理
|
||
- **功能说明**：用户管理、帖子管理、分类管理、对象存储配置、AI 模型配置、知识库管理、导航站管理、项目管理
|
||
- **实现方式**：`backend/routers/admin.py` + 前端 `views/admin/` 10 个管理页面，仅管理员可访问
|
||
- **优点**：完整的运营管理能力
|
||
|
||
## 业务流程
|
||
|
||
### 整体流程图
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[用户注册] --> B{管理员审核}
|
||
B -->|通过| C[登录系统]
|
||
B -->|拒绝| A
|
||
C --> D[首页信息流]
|
||
D --> E[写文章]
|
||
D --> F[AI工具库]
|
||
D --> G[导航/项目/知识库]
|
||
E --> H[Markdown编辑]
|
||
H --> I[AI智能排版]
|
||
H --> J[上传图片/附件]
|
||
H --> K[发布/保存草稿]
|
||
F --> L[需求理解助手]
|
||
F --> M[架构选型助手]
|
||
F --> N[联网搜索]
|
||
F --> O[API Hub]
|
||
G --> P[导航站]
|
||
G --> Q[开源项目]
|
||
G --> R[团队知识库]
|
||
```
|
||
|
||
### 内容发布流程
|
||
|
||
1. 用户进入文章编辑器，选择分类和标签
|
||
2. 使用 Markdown 编写内容，可上传图片到 COS
|
||
3. 可选使用 AI 智能排版一键优化格式
|
||
4. 保存为草稿或直接发布
|
||
5. 发布后自动提取首图作为封面
|
||
6. 其他用户可点赞、收藏、评论，触发通知
|
||
|
||
### API 调用链路
|
||
|
||
| 接口路径 | 方法 | 功能 | 认证 |
|
||
|---------|------|------|------|
|
||
| /api/auth/register | POST | 用户注册 | 无 |
|
||
| /api/auth/login | POST | 用户登录 | 无 |
|
||
| /api/auth/me | GET | 获取当前用户 | JWT |
|
||
| /api/auth/profile | PUT | 更新资料/头像 | JWT |
|
||
| /api/posts | GET/POST | 帖子列表/发布 | JWT |
|
||
| /api/posts/feed | GET | 关注信息流 | JWT |
|
||
| /api/posts/hot | GET | 热门帖子 | JWT |
|
||
| /api/posts/{id} | GET/PUT/DELETE | 帖子详情/编辑/删除 | JWT |
|
||
| /api/posts/{id}/like | POST | 点赞/取消 | JWT |
|
||
| /api/posts/{id}/collect | POST | 收藏/取消 | JWT |
|
||
| /api/posts/{id}/comments | GET/POST | 评论列表/发表 | JWT |
|
||
| /api/upload/image | POST | 上传图片 | JWT |
|
||
| /api/upload/attachment | POST | 上传附件 | JWT |
|
||
| /api/ai/format | POST | AI 智能排版 | JWT |
|
||
| /api/requirement/analyze | POST | 需求分析（SSE） | JWT |
|
||
| /api/architecture/analyze | POST | 架构分析（SSE） | JWT |
|
||
| /api/web-search/search | POST | 联网搜索（SSE） | JWT |
|
||
| /api/api-hub/* | GET/POST/PUT/DELETE | API Hub 管理 | Hub Token |
|
||
| /api/kb/* | GET/POST/PUT/DELETE | 知识库管理 | Kb Token |
|
||
| /api/nav/* | GET/POST/PUT/DELETE | 导航站管理 | JWT |
|
||
| /api/projects/* | GET/POST | 项目管理 | JWT |
|
||
| /api/users/{id} | GET | 用户主页 | JWT |
|
||
| /api/users/{id}/follow | POST | 关注/取消 | JWT |
|
||
| /api/notifications | GET | 通知列表 | JWT |
|
||
| /api/search | GET | 全文搜索 | JWT |
|
||
| /api/admin/* | GET/POST/PUT/DELETE | 后台管理 | JWT + Admin |
|
||
| /api/admin/models/* | GET/POST/PUT/DELETE | AI 模型管理 | JWT + Admin |
|
||
|
||
## 技术栈
|
||
|
||
| 分类 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| **后端框架** | FastAPI | 0.115.0 |
|
||
| **ASGI 服务器** | Uvicorn | 0.30.0 |
|
||
| **ORM** | SQLAlchemy | 2.0.35 |
|
||
| **数据库** | MySQL | 8.0 |
|
||
| **数据库驱动** | PyMySQL | 1.1.2 |
|
||
| **JWT 认证** | python-jose | 3.3.0 |
|
||
| **密码哈希** | passlib + bcrypt | 1.7.4 / 4.0.1 |
|
||
| **HTTP 客户端** | httpx | 0.27.0 |
|
||
| **AI - OpenAI** | openai | 1.51.0 |
|
||
| **AI - Anthropic** | anthropic | 0.34.0 |
|
||
| **AI - Google** | google-generativeai | 0.8.0 |
|
||
| **对象存储** | 腾讯云 COS (cos-python-sdk-v5) | 运行时安装 |
|
||
| **图像处理** | Pillow | 10.4.0 |
|
||
| **前端框架** | Vue | 3.5.30 |
|
||
| **前端路由** | Vue Router | 4.6.4 |
|
||
| **状态管理** | Pinia | 3.0.4 |
|
||
| **HTTP 客户端** | Axios | 1.14.0 |
|
||
| **Markdown 渲染** | markdown-it | 14.1.1 |
|
||
| **代码高亮** | highlight.js | 11.11.1 |
|
||
| **图表绘制** | Mermaid | 11.13.0 |
|
||
| **CSS 框架** | Tailwind CSS | 4.2.2 |
|
||
| **构建工具** | Vite | 8.0.1 |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
BianCheng/
|
||
├── backend/
|
||
│ ├── main.py # FastAPI 应用入口，路由注册
|
||
│ ├── config.py # 全局配置（数据库、JWT、AI模型）
|
||
│ ├── database.py # SQLAlchemy 连接和会话管理
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── .env # 环境变量
|
||
│ ├── models/ # 数据库 ORM 模型（18张表）
|
||
│ │ ├── user.py # 用户
|
||
│ │ ├── post.py # 经验帖
|
||
│ │ ├── comment.py # 评论
|
||
│ │ ├── like.py # 赞和收藏
|
||
│ │ ├── follow.py # 关注关系
|
||
│ │ ├── notification.py # 通知
|
||
│ │ ├── ai_model.py # AI 模型配置
|
||
│ │ ├── attachment.py # 附件
|
||
│ │ ├── conversation.py # AI 对话
|
||
│ │ ├── shared_api.py # 共享 API
|
||
│ │ ├── knowledge_base.py # 知识库
|
||
│ │ ├── category.py # 文章分类
|
||
│ │ ├── nav_category.py # 导航分类
|
||
│ │ ├── nav_link.py # 导航链接
|
||
│ │ ├── project.py # 开源项目
|
||
│ │ ├── bookmark.py # 网站收藏
|
||
│ │ └── system_config.py # 系统配置
|
||
│ ├── routers/ # API 路由（18个模块）
|
||
│ │ ├── auth.py # 认证（注册/登录/资料）
|
||
│ │ ├── posts.py # 帖子 CRUD + 互动
|
||
│ │ ├── users.py # 用户主页 + 关注
|
||
│ │ ├── upload.py # 图片/附件上传（COS）
|
||
│ │ ├── ai_format.py # AI 智能排版
|
||
│ │ ├── ai_models.py # AI 模型管理
|
||
│ │ ├── requirement.py # 需求理解助手
|
||
│ │ ├── architecture.py # 架构选型助手
|
||
│ │ ├── web_search.py # 联网搜索
|
||
│ │ ├── knowledge_base.py # 知识库
|
||
│ │ ├── shared_api.py # API Hub
|
||
│ │ ├── nav.py # 导航站
|
||
│ │ ├── projects.py # 开源项目
|
||
│ │ ├── bookmarks.py # 网站收藏
|
||
│ │ ├── notifications.py # 消息通知
|
||
│ │ ├── search.py # 搜索
|
||
│ │ └── admin.py # 后台管理
|
||
│ ├── schemas/ # Pydantic 数据校验
|
||
│ ├── services/ # 业务逻辑（AI 调用）
|
||
│ └── uploads/ # 本地上传目录（COS 降级）
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── main.js # Vue 应用入口
|
||
│ │ ├── App.vue # 根组件
|
||
│ │ ├── style.css # 全局样式
|
||
│ │ ├── router/index.js # 路由定义（前台+后台）
|
||
│ │ ├── stores/ # Pinia 状态管理
|
||
│ │ │ ├── user.js # 用户状态
|
||
│ │ │ └── tabs.js # 标签页
|
||
│ │ ├── api/
|
||
│ │ │ ├── index.js # Axios 配置 + 拦截器
|
||
│ │ │ └── modules.js # API 模块（20+）
|
||
│ │ └── views/ # 页面组件
|
||
│ │ ├── Home.vue # 首页信息流
|
||
│ │ ├── PostEditor.vue # 文章编辑器
|
||
│ │ ├── PostDetail.vue # 文章详情
|
||
│ │ ├── Profile.vue # 个人资料（头像上传）
|
||
│ │ ├── ToolHub.vue # 工具库
|
||
│ │ ├── RequirementAssistant.vue # 需求助手
|
||
│ │ ├── ArchitectureAssistant.vue # 架构助手
|
||
│ │ ├── WebSearch.vue # 联网搜索
|
||
│ │ ├── ApiHub.vue # API Hub
|
||
│ │ ├── KnowledgeBase.vue # 知识库
|
||
│ │ ├── Navigation.vue # 导航站
|
||
│ │ ├── Projects.vue # 开源项目
|
||
│ │ └── admin/ # 后台管理（10个组件）
|
||
│ ├── package.json
|
||
│ └── vite.config.js
|
||
└── biancheng_full.sql # 数据库 SQL 转储
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
### 环境要求
|
||
- Python 3.9+
|
||
- Node.js 18+
|
||
- MySQL 8.0
|
||
|
||
### 启动步骤
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <repo-url> BianCheng
|
||
cd BianCheng
|
||
|
||
# 2. 后端
|
||
cd backend
|
||
python -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
pip install cos-python-sdk-v5 # COS 对象存储（必装）
|
||
|
||
# 3. 配置环境变量
|
||
cp .env .env.local
|
||
# 编辑 .env 配置 DATABASE_URL 和 AI API Key
|
||
|
||
# 4. 创建数据库
|
||
mysql -u root -p -e "CREATE DATABASE biancheng CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||
|
||
# 5. 启动后端（自动建表）
|
||
python main.py
|
||
# 后端运行在 http://localhost:8000
|
||
|
||
# 6. 前端（新终端）
|
||
cd ../frontend
|
||
npm install
|
||
npm run dev
|
||
# 前端运行在 http://localhost:5173
|
||
```
|
||
|
||
## 服务器部署
|
||
|
||
### 部署步骤
|
||
|
||
```bash
|
||
# 1. 本地编译前端
|
||
cd frontend && npm run build
|
||
|
||
# 2. 上传文件到服务器
|
||
# - backend/ 整个目录 → /www/wwwroot/BianCheng/backend/
|
||
# - frontend/dist/ → /www/wwwroot/BianCheng/frontend/dist/
|
||
# ⚠️ 不要上传 venv 虚拟环境，在服务器重建
|
||
|
||
# 3. 服务器配置 .env（生产环境）
|
||
cat > /www/wwwroot/BianCheng/backend/.env << 'EOF'
|
||
DATABASE_URL=mysql+pymysql://biancheng:biancheng@127.0.0.1:3306/biancheng?charset=utf8mb4
|
||
SECRET_KEY=your-production-secret-key
|
||
ARK_API_KEY=your-ark-api-key
|
||
ARK_ENDPOINT=ep-xxxxx
|
||
EOF
|
||
|
||
# 4. 安装 Python 依赖
|
||
cd /www/wwwroot/BianCheng/backend
|
||
pip3 install -r requirements.txt
|
||
pip3 install cos-python-sdk-v5
|
||
|
||
# 5. Nginx 配置要点
|
||
# - 前端静态文件指向 frontend/dist/
|
||
# - /api 反向代理到后端 127.0.0.1:8000
|
||
# - client_max_body_size 20m（支持附件上传）
|
||
# - SPA 路由 try_files $uri /index.html
|
||
|
||
# 6. 启动后端（宝塔/supervisor/systemd）
|
||
cd /www/wwwroot/BianCheng/backend
|
||
python main.py
|
||
```
|
||
|
||
### Nginx 配置示例
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl;
|
||
server_name your-domain.com;
|
||
|
||
root /www/wwwroot/BianCheng/frontend/dist;
|
||
client_max_body_size 20m;
|
||
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
location /api {
|
||
proxy_pass http://127.0.0.1:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_read_timeout 300s;
|
||
}
|
||
|
||
location /uploads {
|
||
proxy_pass http://127.0.0.1:8000/uploads;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 数据库
|
||
|
||
### 表结构说明
|
||
|
||
| 分类 | 表名 | 说明 |
|
||
|------|------|------|
|
||
| **用户系统** | users | 用户信息（含审核、封禁状态） |
|
||
| **用户系统** | follows | 关注关系 |
|
||
| **用户系统** | notifications | 消息通知 |
|
||
| **内容管理** | posts | 经验帖（含草稿） |
|
||
| **内容管理** | comments | 评论 |
|
||
| **内容管理** | likes | 点赞记录 |
|
||
| **内容管理** | collects | 收藏记录 |
|
||
| **内容管理** | categories | 文章分类 |
|
||
| **内容管理** | attachments | 文件附件 |
|
||
| **AI 功能** | ai_model_configs | AI 模型配置 |
|
||
| **AI 功能** | conversations | AI 对话记录 |
|
||
| **AI 功能** | messages | 对话消息 |
|
||
| **知识库** | kb_categories | 知识库分类 |
|
||
| **知识库** | kb_items | 知识库条目 |
|
||
| **API Hub** | shared_api_categories | API 分类 |
|
||
| **API Hub** | shared_apis | 共享 API |
|
||
| **API Hub** | shared_api_logs | API 调用日志 |
|
||
| **导航站** | nav_categories | 导航分类 |
|
||
| **导航站** | nav_links | 导航链接（含审核） |
|
||
| **开源项目** | projects | 项目信息 |
|
||
| **开源项目** | project_collects | 项目收藏 |
|
||
| **其他** | bookmarks | 网站收藏 |
|
||
| **其他** | system_config | 系统配置（COS等） |
|
||
|
||
## 环境变量
|
||
|
||
### backend/.env
|
||
|
||
```bash
|
||
# 数据库（MySQL 8.0）
|
||
DATABASE_URL=mysql+pymysql://root:root@127.0.0.1:3306/biancheng?charset=utf8mb4
|
||
|
||
# JWT 密钥（生产环境必须更换）
|
||
SECRET_KEY=your-secret-key-change-in-production
|
||
|
||
# AI 模型 API Key（至少配置一个，也可在后台模型管理中配置）
|
||
OPENAI_API_KEY=
|
||
ANTHROPIC_API_KEY=
|
||
GOOGLE_API_KEY=
|
||
DEEPSEEK_API_KEY=
|
||
|
||
# 火山方舟（豆包大模型 + 联网搜索）
|
||
ARK_API_KEY=
|
||
ARK_ENDPOINT=ep-20260411180700-z6nll
|
||
```
|
||
|
||
| 配置项 | 说明 | 必填 |
|
||
|-------|------|------|
|
||
| DATABASE_URL | MySQL 连接字符串，必须包含 `charset=utf8mb4` | 是 |
|
||
| SECRET_KEY | JWT 签名密钥，生产环境必须更换 | 是 |
|
||
| AI API Keys | 各服务商密钥，可在后台模型管理中配置 | 至少一个 |
|
||
| ARK_API_KEY | 火山方舟密钥（联网搜索必需） | 联网搜索需要 |
|
||
| ARK_ENDPOINT | 火山方舟模型端点 ID | 联网搜索需要 |
|
||
|
||
### 系统运行配置（system_config 表）
|
||
|
||
| 配置项 | 说明 | 必填 |
|
||
|-------|------|------|
|
||
| cos_secret_id | 腾讯云 COS SecretId | 图片上传需要 |
|
||
| cos_secret_key | 腾讯云 COS SecretKey | 图片上传需要 |
|
||
| cos_bucket | COS 存储桶名称 | 图片上传需要 |
|
||
| cos_region | COS 区域（如 ap-guangzhou） | 图片上传需要 |
|
||
| cos_custom_domain | CDN 自定义域名（可选） | 否 |
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# === 开发 ===
|
||
cd backend && python main.py # 启动后端
|
||
cd frontend && npm run dev # 启动前端开发服务器
|
||
cd frontend && npm run build # 编译前端
|
||
|
||
# === 数据库 ===
|
||
mysql -u root -p biancheng < biancheng_full.sql # 导入数据库
|
||
mysqldump -u root -p biancheng > backup.sql # 备份数据库
|
||
|
||
# === 部署 ===
|
||
pip3 install -r requirements.txt # 安装后端依赖
|
||
pip3 install cos-python-sdk-v5 # 安装 COS SDK（必装）
|
||
|
||
# === 调试 ===
|
||
curl http://localhost:8000/api/health # 健康检查
|
||
tail -f backend/GeekCode.log # 查看后端日志
|
||
```
|