使用说明
Storyplex分析
具有生产级CI/CD管道的多平台同人小说和网络小说分析刮刀。
项目概述
Storyplex Analytics是一个基于Python的应用程序，可以从AO3等平台抓取和分析同人小说数据。它的特点是：
- FastAPI后端 -用于分析和数据访问的RESTful API
- 反应前端 -用于可视化分析的仪表板
- PostgreSQL数据库 -持久数据存储
- MCP 服务器 -AI助手的模型上下文协议集成
快速开始
先决条件
- Python 3.11+
- Docker&Docker编写
- Make（可选，方便命令）
本地开发
# Clone the repository
git clone <repository-url>
cd storyplex-analytics
# Install dependencies
make install-dev
# Run with Docker Compose
make up
# Or run locally
cp .env.example .env
# Edit .env with your configuration
uvicorn src.api.app:app --reload
可用的生成命令
make help # Show all available commands
make install-dev # Install development dependencies
make lint # Run linting (Ruff)
make test # Run unit tests
make security-scan # Run SAST + SCA security scans
make docker-build # Build Docker image
make docker-test # Test Docker container
make all # Run full CI pipeline locally
CI/CD管道
该项目使用GitHub Actions和DevSecOps原则实现了一个生产级CI/CD管道。
管道结构
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Checkout │────▶│Setup Runtime│────▶│ Linting │
└─────────────┘ └─────────────┘ └─────────────┘
│
┌───────────────────────────────────────┼───────────────────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ SAST │ │ SCA │ │ Unit Tests │
│ (Bandit) │ │ (pip-audit) │ │ (pytest) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────────────────────────────┼───────────────────────────────────────┘
│
▼
┌─────────────┐
│ Build │
│ (Python) │
└─────────────┘
│
▼
┌─────────────┐
│Docker Build │
└─────────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Image Scan │ │Runtime Test │ │ CodeQL │
│ (Trivy) │ │(Smoke Test) │ │ Analysis │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└──────────────────────┼──────────────────────┘
│
▼
┌─────────────┐
│ Docker Push │
│ (DockerHub) │
└─────────────┘
│
▼
┌─────────────┐
│ CD Deploy │
│ (Kubernetes)│
└─────────────┘
CI/CD阶段说明
| 阶段 | 工具 | 目的 | 为什么重要 |
|---|---|---|---|
| 棉绒 | Ruff | 执行编码标准 | 防止技术债务并保持代码一致性 |
| 先科 | Bandit+CodeQL | 静态安全分析 | 检测代码中的OWASP前10个漏洞 |
| 供应链攻击 | pip审计 | 依赖漏洞扫描 | 识别依赖关系中的供应链风险 |
| 单元测试 | pytest | 验证业务逻辑 | 防止回归并确保正确性 |
| 构建 | Python构建 | 打包应用程序 | 验证项目配置 |
| Docker构建 | Docker | 创建容器镜像 | 确保部署一致 |
| 图像扫描 | Trivy | 容器漏洞扫描 | 防止易受攻击的图像被运送 |
| 运行时测试 | Docker | 冒烟测试容器 | 验证容器是否可运行 |
| Docker推送 | DockerHub | 发布可信映像 | 启用下游CD |
| CD部署 | Kubernetes | 部署到集群 | 将应用程序交付到生产环境 |
CD管道（持续部署）
CI成功完成后，CD管道会自动部署到Kubernetes。
CD架构
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ CI Passes │────▶│ Docker Push │────▶│ CD Trigger │────▶│ K8s │
│ │ │ :sha-xxx │ │ │ │ Deployment │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
部署选项
| 选项 | 描述 | 用例 |
|---|---|---|
| 种类（工作流程中） | GitHub操作中的短暂K8s集群 | 测试、演示、作业 |
| 云团 | 部署到Civo、GKE、EKS等。 | 生产部署 |
Kubernetes清单
位于 k8s/ 目录：
| 文件 | 目的 |
|---|---|
deployment.yaml |
吊舱部署规范 |
service.yaml |
用于接入的NodePort服务 |
手动运行CD
您可以从GitHub Actions手动触发CD管道：
- 首选 行动 → CD管道
- 点击 运行工作流
- 可选地指定图像标签（默认为
latest)
安全集成（DevSecOps）
此管道实现 左移安保 -在开发早期发现漏洞：
-
SAST（静态应用程序安全测试）
- Bandit扫描Python代码以查找安全问题
- CodeQL执行深度语义分析
- 结果显示在GitHub安全选项卡中
-
软件组成分析
- pip审计检查与已知CVE的依赖关系
- 识别易受攻击的第三方库
-
集装箱扫描
- Trivy扫描Docker镜像以查找操作系统和库漏洞
- 阻止部署具有关键/高漏洞的映像
GitHub机密配置
在GitHub存储库设置中配置以下机密：
| 秘密名称 | 目的 | 如何获取 |
|---|---|---|
DOCKERHUB_USERNAME |
Docker注册表用户名 | 您的DockerHub用户名 |
DOCKERHUB_TOKEN |
安全注册表访问 | 生成于 DockerHub安全设置 |
设置秘密
- 转到您的GitHub存储库
- 导航至 设置 → 秘密与变量 → 行动
- 点击 新仓库密钥
- 将每个秘密与其对应的值相加
⚠️ 重要：切勿在代码中硬编码机密或将其提交到存储库。
在本地运行CI管道
您可以使用Make在本地模拟CI管道：
# Run full pipeline
make all
# Or run individual stages
make lint # Code quality
make test # Unit tests
make sast # Security scan (SAST)
make sca # Dependency scan (SCA)
make docker-build # Build image
make docker-scan # Scan image (requires Trivy)
make docker-test # Smoke test
项目结构
storyplex-analytics/
├── .github/
│ └── workflows/
│ ├── ci.yml # CI pipeline (build, test, scan, push)
│ └── cd.yml # CD pipeline (deploy to K8s)
├── k8s/
│ ├── deployment.yaml # Pod deployment
│ └── service.yaml # NodePort service
├── src/
│ ├── api/ # FastAPI application
│ ├── db/ # Database models & connection
│ ├── scrapers/ # Web scrapers
│ └── mcp_server.py # MCP server implementation
├── tests/ # Unit tests
├── frontend/ # React frontend
├── Dockerfile # Container image definition
├── docker-compose.yml # Local development setup
├── Makefile # Development commands
├── pyproject.toml # Python project configuration
├── bandit.yaml # SAST configuration
└── README.md # This file
环境变量
复制 .env.example 到 .env 并配置：
DATABASE_URL=postgresql://user:password@localhost:5432/storyplex
ANTHROPIC_API_KEY=your-api-key # For LLM features
贡献
- 创建要素分支
- 进行更改
- 确保所有CI检查通过(
make all) - 提交拉取请求
