Skip to content

生产级别部署：完整 Nexus 系统云端部署与 CICD 流水线 #269

Open
Open
生产级别部署：完整 Nexus 系统云端部署与 CICD 流水线#269
Assignees
cubxxw
Labels
deploymentenhancementNew feature or requesturgent
Milestone
v0.1
@kubbot

Description

@kubbot
kubbot
opened on Jul 22, 2025

🎯 项目概述

基于技术设计文档，实现 Nexus AI 阅读助手系统的完整生产级别部署，构建从开发到部署的全自动化 CICD 流水线。

🏗️ 系统架构设计

根据技术设计文档，部署以下核心组件：

微服务架构

graph TB
    subgraph "Cloud Infrastructure"
        LB[负载均衡器]
        
        subgraph "Frontend Layer"
            WEB[Web App - Next.js]
            ADMIN[Admin Panel - Vite]
            EXT[Browser Extension]
        end
        
        subgraph "API Gateway Layer"
            GW[API Gateway - FastAPI<br/>路由、鉴权、限流、请求转换]
        end
        
        subgraph "Backend Services"
            USER[用户服务<br/>User Service]
            CONTENT[内容服务<br/>Content Service]
            AGENT[处理服务/Agent<br/>Processing Service]
            NOTEBOOK[Notebook 服务<br/>Notebook Service]
            PROMPT[Prompt 服务<br/>Prompt Service]
        end
        
        subgraph "Data Layer"
            PG[PostgreSQL<br/>关系型数据库]
            REDIS[Redis<br/>缓存]
            VECTOR[向量数据库<br/>ChromaDB/Pinecone]
        end
        
        subgraph "External Services"
            LLM[LLM 服务<br/>LiteLLM]
            MONITOR[监控服务<br/>Langfuse]
        end
    end
    
    LB --> WEB
    LB --> ADMIN
    WEB --> GW
    ADMIN --> GW
    EXT --> GW
    
    GW --> USER
    GW --> CONTENT
    GW --> AGENT
    GW --> NOTEBOOK
    GW --> PROMPT
    
    USER --> PG
    CONTENT --> PG
    NOTEBOOK --> PG
    PROMPT --> PG
    
    AGENT --> VECTOR
    USER --> REDIS
    CONTENT --> REDIS
    AGENT --> REDIS
    
    AGENT --> LLM
    AGENT --> MONITOR
Loading

📋 部署任务清单

Phase 1: 基础设施准备 (1-2天)

  • 云服务商选择与配置

    • 推荐使用 AWS/Azure/GCP 或 Railway/Fly.io
    • 配置 VPC 网络和安全组
    • 设置域名解析 (Cloudflare DNS)

  • 容器化完善

    • 完善现有 Docker 镜像构建
    • 优化 docker-compose.yml 配置
    • 添加健康检查和优雅关闭

Phase 2: 数据库与存储 (1-2天)

  • PostgreSQL 生产配置

    • 配置主从复制和自动备份
    • 设置连接池和性能优化
    • 数据迁移脚本完善

  • 缓存层部署

    • Redis 集群配置
    • 缓存策略优化
    • 会话存储配置

  • 向量数据库部署

    • ChromaDB 或 Pinecone 配置
    • RAG 索引初始化
    • 数据同步策略

Phase 3: 后端服务部署 (2-3天)

  • 微服务容器化部署

    • 用户服务 (User Service)
    • 内容服务 (Content Service)
    • 处理服务 (Processing Service/Agent)
    • Notebook 服务
    • Prompt 服务

  • API Gateway 配置

    • FastAPI 网关部署
    • 路由规则配置
    • JWT 认证集成
    • 限流和熔断配置

  • 外部服务集成

    • LiteLLM 配置和密钥管理
    • Langfuse 监控集成
    • 文本分段服务 (MinerU)

Phase 4: 前端应用部署 (1-2天)

  • Web 应用部署

    • Next.js 应用构建和部署 (Vercel/Cloudflare Pages)
    • 环境变量配置
    • CDN 和静态资源优化

  • 管理后台部署

    • Vite 构建的管理面板
    • 管理员权限配置
    • 后台功能集成测试

  • 浏览器插件发布

    • Chrome/Firefox 插件商店发布
    • 插件更新机制
    • 用户引导和帮助文档

Phase 5: CICD 流水线 (2-3天)

  • GitHub Actions 配置

    • 自动化测试流水线
    • 多环境部署 (dev/staging/production)
    • 自动化镜像构建和推送

  • 部署自动化

    • Helm Charts 完善
    • Kubernetes 部署配置
    • 滚动更新策略

  • 环境管理

    • 开发环境自动部署
    • 预发布环境配置
    • 生产环境部署审批流程

Phase 6: 监控与可观测性 (1-2天)

  • 监控系统部署

    • Prometheus + Grafana
    • 应用性能监控 (APM)
    • 错误追踪 (Sentry)

  • 日志系统

    • 集中化日志收集
    • 结构化日志格式
    • 日志分析和告警

  • 健康检查

    • 各服务健康检查端点
    • 监控大盘配置
    • 告警规则设置

Phase 7: 安全与优化 (1-2天)

  • 安全配置

    • HTTPS 证书配置
    • 安全头设置
    • 敏感信息加密存储

  • 性能优化

    • 数据库查询优化
    • 缓存策略调优
    • 静态资源压缩

  • 负载测试

    • 压力测试执行
    • 性能瓶颈识别
    • 扩展性验证

🔧 技术实现要点

Docker 配置优化

  • 多阶段构建减少镜像体积
  • 健康检查和优雅关闭
  • 资源限制和环境变量管理

Kubernetes 部署配置

# 示例配置结构
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nexus-backend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nexus-backend
  template:
    metadata:
      labels:
        app: nexus-backend
    spec:
      containers:
      - name: backend
        image: nexus/backend:latest
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: nexus-secrets
              key: database-url
        livenessProbe:
          httpGet:
            path: /api/v1/health
            port: 8000
        readinessProbe:
          httpGet:
            path: /api/v1/ready
            port: 8000

CICD 流水线配置

# .github/workflows/deploy.yml
name: Deploy to Production
on:
  push:
    branches: [main]
    tags: ['v*']
  
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build and test
        run: |
          make all
          make docker-build
      - name: Deploy to staging
        if: github.ref == 'refs/heads/main'
        run: make deploy ENVIRONMENT=staging
      - name: Deploy to production
        if: startsWith(github.ref, 'refs/tags/')
        run: make deploy ENVIRONMENT=production

🎯 环境配置

环境变量管理

基于现有的 .env.example，配置不同环境的变量：

# Production Environment Variables
ENVIRONMENT=production
DOMAIN=nexus.telepace.cc
STACK_NAME=nexus-production

# Database
POSTGRES_SERVER=nexus-db-cluster.internal
POSTGRES_PASSWORD=***
POSTGRES_DB=nexus_prod

# LLM Services
SECRET_KEY=***
OPENAI_API_KEY=***
ANTHROPIC_API_KEY=***

# Monitoring
LANGFUSE_HOST=https://langfuse.nexus.telepace.cc
SENTRY_DSN=***

域名配置建议

  • 主应用: nexus.telepace.cc
  • 管理后台: admin.nexus.telepace.cc
  • API: api.nexus.telepace.cc
  • 监控: monitor.nexus.telepace.cc

📊 成功指标

性能指标

  • 响应时间: API P95 响应时间 < 500ms
  • 可用性: 系统可用性 > 99.9%
  • 并发处理: 支持 100+ 并发用户
  • 数据处理: AI 处理任务响应时间 < 30s

部署指标

  • 自动化程度: 100% 自动化部署
  • 回滚时间: < 5分钟
  • 部署频率: 支持每日多次发布
  • 错误率: 部署成功率 > 95%

✅ 验收标准

功能验收

  • 所有核心功能在生产环境正常运行
  • 用户注册、登录、内容处理完整流程测试通过
  • AI 分析、对话、Notebook 功能正常
  • 浏览器插件正常工作

性能验收

  • 系统能够承受预期的用户负载
  • 数据库查询性能符合要求
  • 静态资源加载速度优化
  • 移动端访问体验良好

运维验收

  • 监控告警正常工作
  • 日志收集和分析可用
  • 自动化部署流程验证
  • 数据备份和恢复机制测试

安全验收

  • HTTPS 证书正确配置
  • 敏感数据加密存储
  • API 访问权限控制正确
  • 安全扫描无高危漏洞

🚀 后续规划

短期目标 (1个月内)

  • 完成基础部署和 CICD 配置
  • 建立监控和告警体系
  • 优化性能和安全配置

中期目标 (3个月内)

  • 实现多区域部署
  • 完善灾备和恢复机制
  • 建立自动扩缩容机制

长期目标 (6个月内)

  • 云原生架构优化
  • 成本优化和资源管理
  • 国际化部署支持

🔗 相关文档

👥 任务分配

主要负责人: @cubxxw (系统架构、后端服务、CICD)
协作人员: @Neo-Neooo (前端部署、用户体验测试)

预估工期: 2-3周
优先级: 高
里程碑: v0.1

Metadata

Metadata

Assignees

Labels

deploymentenhancementNew feature or requesturgent

Type

No type

Projects

nexus

Status

Backlog

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions