# octopus

**Repository Path**: mr-chen-frog/octopus

## Basic Information

- **Project Name**: octopus
- **Description**: 这是一个 CI/CD 管理系统，用于管理 Docker 容器的构建、部署和监控。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Octopus CI/CD 管理系统

**文档编号**: DOC-001  
**文档类型**: 项目概述  
**最后更新**: 2025-01-15

一个现代化的 Docker CI/CD 管理系统，支持容器化部署、构建流水线和监控管理。

## 📁 项目结构

```
octopus/
├── backend/                 # 后端服务 (FastAPI)
│   ├── src/app/            # 应用核心代码
│   │   ├── api/           # API 路由
│   │   ├── core/          # 核心配置和工具
│   │   ├── models/        # 数据模型
│   │   ├── schemas/       # Pydantic 模式
│   │   ├── services/      # 业务逻辑服务
│   │   └── tasks/         # 后台任务
│   ├── alembic/           # 数据库迁移
│   │   └── versions/     # 迁移版本文件
│   ├── scripts/           # 后端脚本
│   │   ├── create_*.py   # 数据初始化脚本
│   │   └── *.sh          # Shell 脚本
│   ├── Dockerfile         # 后端容器配置
│   └── requirements.txt   # Python 依赖
├── frontend/               # 前端应用 (React + TypeScript)
│   ├── src/               # 前端源代码
│   │   ├── api/           # API 客户端
│   │   ├── components/    # React 组件
│   │   ├── pages/         # 页面组件
│   │   ├── hooks/         # 自定义 Hooks
│   │   ├── stores/        # 状态管理
│   │   ├── types/         # TypeScript 类型定义
│   │   └── utils/         # 工具函数
│   ├── public/            # 静态资源
│   ├── Dockerfile         # 前端容器配置
│   └── package.json       # Node.js 依赖
├── deploy/                 # 部署配置
│   ├── docker-compose.yml # Docker Compose 配置
│   ├── nginx.conf         # Nginx 配置
│   ├── init.sql           # 数据库初始化
│   └── ssl/               # SSL 证书目录
├── docs/                   # 项目文档
│   ├── architecture/      # 架构文档 (DOC-100~199)
│   │   ├── arch.md
│   │   ├── database_schema.md
│   │   └── SYSTEM_STATUS.md
│   ├── development/       # 开发文档 (DOC-200~299)
│   │   ├── CI_CD_SYSTEM_GUIDE.md
│   │   ├── DOCKER_INTEGRATION.md
│   │   ├── LOGGING_GUIDE.md
│   │   └── QUICK_REFERENCE.md
│   ├── internal/          # 内部文档（不公开）
│   │   ├── analysis/      # 分析报告
│   │   ├── migration/     # 迁移文档
│   │   ├── research/      # 研究报告
│   │   └── reports/       # 验证报告
│   ├── INDEX.md           # 文档索引 (DOC-002)
│   └── README.md          # 文档说明
├── scripts/                # 项目级脚本
│   └── auto_add_orbstack_server.py
├── config/                 # 配置文件
│   ├── env.example         # 环境变量示例
│   └── todo-rules.json     # 任务规则配置
├── tests/                  # 测试代码
│   ├── api/               # API 测试
│   ├── integration/       # 集成测试
│   └── unit/              # 单元测试
├── specs/                  # 规格说明文档
│   └── 001-octopus-ci-cd/ # 功能规格
├── start.sh               # 启动脚本
└── README.md              # 项目说明 (DOC-001)
```

## 🚀 快速开始

### 开发环境启动

```bash
# 一键启动开发环境（推荐）
./start.sh dev

# 仅启动后端
./start.sh backend

# 仅启动前端
./start.sh frontend

# Docker 模式 - 使用 Docker Compose 启动完整环境
./start.sh docker

# Docker 模式 - 使用指定的 compose 文件
./start.sh docker docker-compose.orbstack.yml  # OrbStack 配置
./start.sh docker docker-compose.prod.yml      # 生产配置
```

### 环境配置

1. 复制环境变量配置：
```bash
cp config/env.example .env
```

2. 编辑 `.env` 文件，配置数据库连接等信息

3. 启动服务：
```bash
./start.sh dev
```

## 🛠️ 技术栈

### 后端
- **FastAPI** - 现代 Python Web 框架
- **PostgreSQL** - 主数据库
- **Redis** - 缓存和会话存储
- **SQLAlchemy** - ORM
- **Alembic** - 数据库迁移
- **Docker** - 容器化

### 前端
- **React 18** - 用户界面框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Tailwind CSS** - 样式框架
- **Zustand** - 状态管理

### 部署
- **Docker Compose** - 容器编排
- **Nginx** - 反向代理
- **PostgreSQL** - 生产数据库
- **Redis** - 生产缓存

## 📚 文档

详细文档请查看 [文档索引](docs/INDEX.md) (DOC-002)：

### 快速开始
- [DOC-001 项目 README](README.md) - 项目概述
- [DOC-002 文档索引](docs/INDEX.md) - 完整文档列表
- [DOC-200 快速参考](docs/development/QUICK_REFERENCE.md) - 开发快速参考

### 架构文档 (DOC-100~199)
- [DOC-100 系统架构](docs/architecture/arch.md) - 系统整体架构设计
- [DOC-101 数据库架构](docs/architecture/database_schema.md) - 数据库表结构和关系
- [DOC-102 系统状态](docs/architecture/SYSTEM_STATUS.md) - 当前系统状态

### 开发文档 (DOC-200~299)
- [DOC-201 CI/CD 系统指南](docs/development/CI_CD_SYSTEM_GUIDE.md) - CI/CD 系统使用指南
- [DOC-202 Docker 集成](docs/development/DOCKER_INTEGRATION.md) - Docker 集成和部署指南
- [DOC-203 日志指南](docs/development/LOGGING_GUIDE.md) - 日志系统使用指南

## 🔧 开发

### 后端开发

```bash
cd backend
pip install -r requirements.txt
cd src
uvicorn app.main:app --reload
```

### 前端开发

```bash
cd frontend
npm install
npm run dev
```

### 数据库迁移

```bash
cd backend
alembic upgrade head
```

## 🐳 Docker 部署

### Docker Compose 启动

使用 `./start.sh docker` 命令可以一键启动完整的 Docker 环境，包括：
- 后端 API 服务（端口 8000）
- 前端应用（端口 3000）
- PostgreSQL 数据库（端口 5432）
- Redis 缓存（端口 6379）
- Nginx 反向代理（端口 80）

### 访问地址

启动成功后，可以通过以下地址访问：

- **直接访问前端**：http://localhost:3000
- **通过 Nginx 访问**：http://localhost:80
- **后端 API**：http://localhost:8000
- **通过 Nginx 访问 API**：http://localhost:80/api/v1/
- **API 文档**：http://localhost:8000/docs 或 http://localhost:80/docs

### 配置修复说明

如果修改了前端或 Nginx 配置，需要重新构建或重新加载：

#### 重新构建前端镜像

如果修改了 `frontend/Dockerfile` 或 `frontend/nginx.conf`：

```bash
cd deploy
docker compose build frontend
docker compose up -d frontend
```

#### 重新加载 Nginx 配置

如果修改了 `deploy/nginx.conf`：

```bash
cd deploy
docker compose exec nginx nginx -s reload
# 或者重启容器
docker compose restart nginx
```

### 常用 Docker 命令

```bash
# 查看服务状态
cd deploy
docker compose ps

# 查看日志
docker compose logs -f [service_name]  # 例如: docker compose logs -f backend

# 停止所有服务
docker compose down

# 停止并删除数据卷（谨慎使用）
docker compose down -v
```

## 📝 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📋 待办事项

代码质量持续改进中，欢迎贡献：

- ✅ 修复构建持续时间显示问题
- ✅ 优化时间格式化工具
- ⏳ 将内联样式提取到外部 CSS 文件
- ⏳ 完善单元测试覆盖
- ⏳ 优化代码注释和文档

---

**注意**: 这是一个 CI/CD 管理系统，用于管理 Docker 容器的构建、部署和监控。