# 生产环境部署
**本文档引用的文件**
- [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)
## 目录
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["负载均衡/反向代理
Nginx"]
subgraph "应用层"
FE["前端容器
Next.js"]
BE["后端容器
FastAPI(Uvicorn)"]
end
subgraph "数据层"
DB["数据库
PostgreSQL"]
RC["缓存/队列
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
SSL/TLS 终止
静态资源缓存"]
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延迟、吞吐量、资源占用
- 可靠性：故障切换、恢复时间、数据一致性校验