14 KiB

Raw Permalink Blame History

生产环境部署

**本文档引用的文件** - [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)

简介

本指南面向GEO项目的生产环境部署，覆盖以下关键主题：

部署架构：后端服务、数据库、缓存与前端容器编排
Nginx反向代理、SSL证书与负载均衡建议
环境变量与安全配置：数据库、Redis、API密钥与JWT
性能优化：静态资源缓存、Gzip压缩与CDN集成
安全加固：防火墙、访问控制与数据加密
域名与DNS、HTTPS证书申请流程
部署后验证与性能基准测试方法

项目结构

GEO采用多容器编排，后端使用FastAPI，前端使用Next.js，数据库为PostgreSQL，缓存为Redis。开发阶段通过Compose进行联调，生产环境建议以Nginx作为统一入口，结合反向代理、SSL终止与负载均衡。

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

图表来源

章节来源

核心组件

后端服务（FastAPI + Uvicorn）：提供REST API，包含认证、查询词、引用数据与报告接口；内置健康检查端点。
数据库（PostgreSQL）：异步SQLAlchemy引擎连接，支持迁移脚本。
缓存（Redis）：用于任务调度与会话/锁等场景。
前端（Next.js）：开发模式运行，生产建议构建并由Nginx提供静态资源与反代。
引擎与平台适配器：基于Playwright的网页自动化，对接Kimi与文心一格平台。

章节来源

架构总览

下图展示生产环境典型拓扑：Nginx作为入口，负责TLS终止、静态资源分发与反向代理；后端容器提供API；数据库与Redis分别承载持久化与缓存。

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

图表来源

详细组件分析

后端服务（FastAPI）

应用生命周期：启动时初始化调度器，关闭时优雅停机。
CORS策略：开发默认允许本地前端源，生产需收紧为受信域名。
路由模块：认证、查询词、引用数据、报告与即时执行路由。
健康检查：/health端点返回状态。

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 : "返回内容"

图表来源

章节来源

数据库与迁移

异步引擎：使用异步SQLAlchemy与asyncpg。
迁移：初始版本包含用户、查询、引用记录、任务与订阅表，含索引与外键约束。

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

章节来源

引擎与平台适配器

CitationEngine：对指定平台发起查询，执行品牌匹配与竞争品牌检测，并记录结果。
平台适配器：Kimi与文心一言，基于Playwright自动化，具备重试与稳定性等待逻辑。
任务调度：查询任务状态管理，支持失败回退与占位记录。

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(["结束"])

图表来源

章节来源

前端（Next.js）

开发模式：通过Dockerfile直接运行开发服务器。
生产建议：构建产物由Nginx托管，配合缓存与压缩策略。

章节来源

依赖关系分析

后端依赖：FastAPI、Uvicorn、SQLAlchemy、asyncpg、Pydantic、Redis、APScheduler、Playwright、httpx、python-dotenv等。
前端依赖：Next.js、Radix UI、Tailwind CSS、NextAuth等。
容器编排：Compose定义数据库、Redis、后端与前端服务及其端口映射与健康检查。

graph LR
Backend["后端应用"] --> DB["PostgreSQL"]
Backend --> Redis["Redis"]
Backend --> Playwright["Playwright 浏览器"]
Frontend["前端应用"] --> Backend

图表来源

章节来源

性能考虑

静态资源缓存：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密钥配置正确，避免请求失败导致任务异常。

章节来源

结论

本指南提供了GEO生产环境部署的完整路径：从容器编排到Nginx反向代理与SSL、从环境变量与安全配置到性能优化与安全加固，并给出了部署后验证与基准测试建议。建议在正式上线前完成域名与DNS解析、证书申请与安装、以及完整的端到端测试。

附录