347 lines
14 KiB
Markdown
347 lines
14 KiB
Markdown
# 生产环境部署
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [docker-compose.yml](file://docker-compose.yml)
|
||
- [backend/Dockerfile](file://backend/Dockerfile)
|
||
- [frontend/Dockerfile](file://frontend/Dockerfile)
|
||
- [backend/app/config.py](file://backend/app/config.py)
|
||
- [backend/app/main.py](file://backend/app/main.py)
|
||
- [backend/app/database.py](file://backend/app/database.py)
|
||
- [backend/requirements.txt](file://backend/requirements.txt)
|
||
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
|
||
- [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py)
|
||
- [backend/app/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py)
|
||
- [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py)
|
||
- [frontend/next.config.mjs](file://frontend/next.config.mjs)
|
||
- [frontend/package.json](file://frontend/package.json)
|
||
- [frontend/tailwind.config.ts](file://frontend/tailwind.config.ts)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本指南面向GEO项目的生产环境部署，覆盖以下关键主题：
|
||
- 部署架构：后端服务、数据库、缓存与前端容器编排
|
||
- Nginx反向代理、SSL证书与负载均衡建议
|
||
- 环境变量与安全配置：数据库、Redis、API密钥与JWT
|
||
- 性能优化：静态资源缓存、Gzip压缩与CDN集成
|
||
- 安全加固：防火墙、访问控制与数据加密
|
||
- 域名与DNS、HTTPS证书申请流程
|
||
- 部署后验证与性能基准测试方法
|
||
|
||
## 项目结构
|
||
GEO采用多容器编排，后端使用FastAPI，前端使用Next.js，数据库为PostgreSQL，缓存为Redis。开发阶段通过Compose进行联调，生产环境建议以Nginx作为统一入口，结合反向代理、SSL终止与负载均衡。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "生产环境"
|
||
LB["负载均衡/反向代理<br/>Nginx"]
|
||
subgraph "应用层"
|
||
FE["前端容器<br/>Next.js"]
|
||
BE["后端容器<br/>FastAPI(Uvicorn)"]
|
||
end
|
||
subgraph "数据层"
|
||
DB["数据库<br/>PostgreSQL"]
|
||
RC["缓存/队列<br/>Redis"]
|
||
end
|
||
end
|
||
LB --> FE
|
||
LB --> BE
|
||
BE --> DB
|
||
BE --> RC
|
||
```
|
||
|
||
图表来源
|
||
- [docker-compose.yml:36-51](file://docker-compose.yml#L36-L51)
|
||
- [backend/Dockerfile:40-41](file://backend/Dockerfile#L40-L41)
|
||
- [frontend/Dockerfile:14-15](file://frontend/Dockerfile#L14-L15)
|
||
|
||
章节来源
|
||
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
|
||
- [backend/Dockerfile:1-41](file://backend/Dockerfile#L1-L41)
|
||
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
|
||
|
||
## 核心组件
|
||
- 后端服务（FastAPI + Uvicorn）：提供REST API，包含认证、查询词、引用数据与报告接口；内置健康检查端点。
|
||
- 数据库（PostgreSQL）：异步SQLAlchemy引擎连接，支持迁移脚本。
|
||
- 缓存（Redis）：用于任务调度与会话/锁等场景。
|
||
- 前端（Next.js）：开发模式运行，生产建议构建并由Nginx提供静态资源与反代。
|
||
- 引擎与平台适配器：基于Playwright的网页自动化，对接Kimi与文心一格平台。
|
||
|
||
章节来源
|
||
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
|
||
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
|
||
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
|
||
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
|
||
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
|
||
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
|
||
- [frontend/package.json:1-40](file://frontend/package.json#L1-L40)
|
||
|
||
## 架构总览
|
||
下图展示生产环境典型拓扑：Nginx作为入口，负责TLS终止、静态资源分发与反向代理；后端容器提供API；数据库与Redis分别承载持久化与缓存。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Internet["互联网"]
|
||
Nginx["Nginx<br/>SSL/TLS 终止<br/>静态资源缓存"]
|
||
subgraph "应用服务"
|
||
API["FastAPI 应用"]
|
||
Worker["任务/调度器"]
|
||
end
|
||
subgraph "数据服务"
|
||
Postgres["PostgreSQL"]
|
||
Redis["Redis"]
|
||
end
|
||
Internet --> Nginx
|
||
Nginx --> API
|
||
Nginx --> |静态资源| Nginx
|
||
API --> Postgres
|
||
API --> Redis
|
||
Worker --> Redis
|
||
Worker --> Postgres
|
||
```
|
||
|
||
图表来源
|
||
- [backend/app/main.py:24-47](file://backend/app/main.py#L24-L47)
|
||
- [backend/app/database.py:6-18](file://backend/app/database.py#L6-L18)
|
||
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)
|
||
|
||
## 详细组件分析
|
||
|
||
### 后端服务（FastAPI）
|
||
- 应用生命周期：启动时初始化调度器，关闭时优雅停机。
|
||
- CORS策略：开发默认允许本地前端源，生产需收紧为受信域名。
|
||
- 路由模块：认证、查询词、引用数据、报告与即时执行路由。
|
||
- 健康检查：/health端点返回状态。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as "客户端"
|
||
participant Nginx as "Nginx"
|
||
participant API as "FastAPI 应用"
|
||
participant DB as "PostgreSQL"
|
||
participant Redis as "Redis"
|
||
Client->>Nginx : "HTTP 请求"
|
||
Nginx->>API : "反向代理转发"
|
||
API->>DB : "数据库查询"
|
||
DB-->>API : "结果"
|
||
API->>Redis : "缓存/任务交互"
|
||
Redis-->>API : "响应"
|
||
API-->>Nginx : "HTTP 响应"
|
||
Nginx-->>Client : "返回内容"
|
||
```
|
||
|
||
图表来源
|
||
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
|
||
- [backend/app/database.py:23-28](file://backend/app/database.py#L23-L28)
|
||
- [backend/app/config.py:7-8](file://backend/app/config.py#L7-L8)
|
||
|
||
章节来源
|
||
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
|
||
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
|
||
|
||
### 数据库与迁移
|
||
- 异步引擎：使用异步SQLAlchemy与asyncpg。
|
||
- 迁移：初始版本包含用户、查询、引用记录、任务与订阅表，含索引与外键约束。
|
||
|
||
```mermaid
|
||
erDiagram
|
||
USERS {
|
||
uuid id PK
|
||
string email UK
|
||
string password_hash
|
||
string name
|
||
string plan
|
||
integer max_queries
|
||
boolean is_active
|
||
timestamp created_at
|
||
timestamp updated_at
|
||
}
|
||
QUERIES {
|
||
uuid id PK
|
||
uuid user_id FK
|
||
string keyword
|
||
string target_brand
|
||
jsonb brand_aliases
|
||
jsonb platforms
|
||
string frequency
|
||
string status
|
||
timestamp last_queried_at
|
||
timestamp next_query_at
|
||
timestamp created_at
|
||
timestamp updated_at
|
||
}
|
||
CITATION_RECORDS {
|
||
uuid id PK
|
||
uuid query_id FK
|
||
string platform
|
||
boolean cited
|
||
integer citation_position
|
||
text citation_text
|
||
jsonb competitor_brands
|
||
text raw_response
|
||
timestamp queried_at
|
||
}
|
||
QUERY_TASKS {
|
||
uuid id PK
|
||
uuid query_id FK
|
||
string platform
|
||
string status
|
||
text error_message
|
||
timestamp scheduled_at
|
||
timestamp started_at
|
||
timestamp completed_at
|
||
}
|
||
SUBSCRIPTIONS {
|
||
uuid id PK
|
||
uuid user_id FK
|
||
string plan
|
||
string status
|
||
date start_date
|
||
date end_date
|
||
numeric amount
|
||
string payment_method
|
||
string payment_id
|
||
timestamp created_at
|
||
}
|
||
USERS ||--o{ QUERIES : "拥有"
|
||
QUERIES ||--o{ CITATION_RECORDS : "产生"
|
||
QUERIES ||--o{ QUERY_TASKS : "调度"
|
||
USERS ||--o{ SUBSCRIPTIONS : "订阅"
|
||
```
|
||
|
||
图表来源
|
||
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:24-111](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L24-L111)
|
||
|
||
章节来源
|
||
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
|
||
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:1-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L1-L128)
|
||
|
||
### 引擎与平台适配器
|
||
- CitationEngine：对指定平台发起查询，执行品牌匹配与竞争品牌检测，并记录结果。
|
||
- 平台适配器：Kimi与文心一言，基于Playwright自动化，具备重试与稳定性等待逻辑。
|
||
- 任务调度：查询任务状态管理，支持失败回退与占位记录。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始执行查询"]) --> InitMatcher["初始化品牌匹配器"]
|
||
InitMatcher --> IteratePlat["遍历平台列表"]
|
||
IteratePlat --> CreateTask["创建/获取任务记录"]
|
||
CreateTask --> SetRunning["标记任务为运行中"]
|
||
SetRunning --> DoQuery["平台查询Playwright"]
|
||
DoQuery --> BrandMatch["品牌匹配与竞争品牌检测"]
|
||
BrandMatch --> SaveRecord["保存引用记录"]
|
||
SaveRecord --> UpdateQueryTime["更新查询时间与下次查询时间"]
|
||
UpdateQueryTime --> NextPlat{"还有平台？"}
|
||
NextPlat --> |是| IteratePlat
|
||
NextPlat --> |否| End(["结束"])
|
||
```
|
||
|
||
图表来源
|
||
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
|
||
- [backend/app/workers/platforms/kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
|
||
- [backend/app/workers/platforms/wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)
|
||
|
||
章节来源
|
||
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
|
||
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
|
||
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
|
||
|
||
### 前端（Next.js）
|
||
- 开发模式：通过Dockerfile直接运行开发服务器。
|
||
- 生产建议：构建产物由Nginx托管，配合缓存与压缩策略。
|
||
|
||
章节来源
|
||
- [frontend/Dockerfile:1-15](file://frontend/Dockerfile#L1-L15)
|
||
- [frontend/package.json:5-9](file://frontend/package.json#L5-L9)
|
||
- [frontend/next.config.mjs:1-5](file://frontend/next.config.mjs#L1-L5)
|
||
|
||
## 依赖关系分析
|
||
- 后端依赖：FastAPI、Uvicorn、SQLAlchemy、asyncpg、Pydantic、Redis、APScheduler、Playwright、httpx、python-dotenv等。
|
||
- 前端依赖：Next.js、Radix UI、Tailwind CSS、NextAuth等。
|
||
- 容器编排：Compose定义数据库、Redis、后端与前端服务及其端口映射与健康检查。
|
||
|
||
```mermaid
|
||
graph LR
|
||
Backend["后端应用"] --> DB["PostgreSQL"]
|
||
Backend --> Redis["Redis"]
|
||
Backend --> Playwright["Playwright 浏览器"]
|
||
Frontend["前端应用"] --> Backend
|
||
```
|
||
|
||
图表来源
|
||
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
|
||
- [docker-compose.yml:4-51](file://docker-compose.yml#L4-L51)
|
||
|
||
章节来源
|
||
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
|
||
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
|
||
|
||
## 性能考虑
|
||
- 静态资源缓存：Nginx启用长期缓存头，结合文件指纹命名策略，减少带宽与延迟。
|
||
- Gzip/压缩：开启gzip或更高效的压缩算法（如Brotli），降低传输体积。
|
||
- CDN集成：将静态资源（图片、JS/CSS）接入CDN，提升全球访问速度与可用性。
|
||
- 数据库优化：合理索引（已有迁移脚本包含索引）、连接池参数调优、慢查询日志与监控。
|
||
- 缓存策略：Redis用于热点数据与任务队列，避免重复计算与高并发下的数据库压力。
|
||
- 前端构建：生产构建开启Tree Shaking、代码分割与懒加载，缩短首屏时间。
|
||
- 反向代理：Nginx作为统一入口，可集中处理压缩、缓存与限流。
|
||
|
||
## 故障排查指南
|
||
- 健康检查：通过/health端点确认后端存活；Compose中数据库与Redis具备健康检查命令。
|
||
- 日志定位：查看Nginx错误日志、后端Uvicorn日志与容器日志；关注数据库连接与Redis连通性。
|
||
- CORS问题：生产环境需将前端域名加入allow_origins白名单，避免跨域阻断。
|
||
- 数据库迁移：确保迁移脚本成功执行，检查表结构与索引是否存在。
|
||
- Playwright依赖：容器内需安装浏览器依赖，确保Playwright可正常启动浏览器实例。
|
||
- API密钥：确认平台API密钥配置正确，避免请求失败导致任务异常。
|
||
|
||
章节来源
|
||
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
|
||
- [docker-compose.yml:16-20](file://docker-compose.yml#L16-L20)
|
||
- [docker-compose.yml:30-34](file://docker-compose.yml#L30-L34)
|
||
- [backend/app/config.py:12-13](file://backend/app/config.py#L12-L13)
|
||
- [backend/app/workers/platforms/kimi.py:21-32](file://backend/app/workers/platforms/kimi.py#L21-L32)
|
||
- [backend/app/workers/platforms/wenxin.py:21-32](file://backend/app/workers/platforms/wenxin.py#L21-L32)
|
||
|
||
## 结论
|
||
本指南提供了GEO生产环境部署的完整路径：从容器编排到Nginx反向代理与SSL、从环境变量与安全配置到性能优化与安全加固，并给出了部署后验证与基准测试建议。建议在正式上线前完成域名与DNS解析、证书申请与安装、以及完整的端到端测试。
|
||
|
||
## 附录
|
||
|
||
### 生产环境部署清单
|
||
- 基础设施
|
||
- 负载均衡/反向代理：Nginx（建议启用TLS终止、静态资源缓存与Gzip/Brotli）
|
||
- 应用容器：后端（FastAPI）、前端（Next.js生产构建）
|
||
- 数据库：PostgreSQL（主从/高可用视规模而定）
|
||
- 缓存：Redis（哨兵/集群视规模而定）
|
||
- 环境变量与安全
|
||
- 数据库连接：DATABASE_URL（生产使用强密码与只读账号）
|
||
- Redis连接：REDIS_URL（网络隔离与ACL）
|
||
- JWT密钥：JWT_SECRET（高强度随机值，定期轮换）
|
||
- 平台API密钥：ZHIPU_API_KEY、TONGYI_API_KEY（最小权限与限额）
|
||
- 配置与优化
|
||
- Nginx：静态资源缓存头、压缩、限流、健康检查探针
|
||
- 后端：连接池大小、超时、日志级别、CORS白名单
|
||
- 数据库：连接数上限、慢查询阈值、备份策略
|
||
- 前端：构建产物缓存、CDN接入、预加载关键资源
|
||
- 安全加固
|
||
- 防火墙：仅开放必要端口（80/443/22等）
|
||
- 访问控制：IP白名单、速率限制、WAF
|
||
- 数据加密：传输加密（TLS）、静态加密（视合规要求）
|
||
- 域名与证书
|
||
- DNS：A/AAAA记录指向负载均衡器；CNAME别名指向子域名
|
||
- 证书：ACME自动签发或商业证书；多域名与SAN
|
||
- 部署后验证与基准测试
|
||
- 功能验证：登录、查询、报告生成、引用检测
|
||
- 性能基准：并发用户数、P95/P99延迟、吞吐量、资源占用
|
||
- 可靠性：故障切换、恢复时间、数据一致性校验 |