# 漏洞管理后端 API

独立的漏洞管理后端 API 服务，提供完整的漏洞生命周期管理功能。

## 功能特性

- ✅ **漏洞管理** - 创建、查询、更新漏洞信息
- ✅ **标签系统** - 灵活的标签分类和管理
- ✅ **发现渠道** - 管理多种漏洞发现来源
- ✅ **高级查询** - 支持多维度筛选和排序
- ✅ **RESTful API** - 标准的 REST 接口设计
- ✅ **独立部署** - 可独立运行，无外部依赖

## 技术栈

- **语言**: Go 1.21+
- **框架**: Gin (HTTP 路由)
- **ORM**: GORM
- **数据库**: MySQL 8.0
- **配置**: Viper
- **日志**: 结构化日志

## API 端点

### 漏洞管理
```
GET    /api/v1/vulnerabilities          获取漏洞列表
POST   /api/v1/vulnerabilities          创建新漏洞
GET    /api/v1/vulnerabilities/config   获取配置信息
```

### 标签管理
```
GET    /api/v1/vulnerability-tags          获取标签列表
POST   /api/v1/vulnerability-tags          创建标签
PUT    /api/v1/vulnerability-tags/:id      更新标签
DELETE /api/v1/vulnerability-tags/:id      删除标签
GET    /api/v1/vulnerability-tags/stats    标签统计
```

### 发现渠道管理
```
GET    /api/v1/vulnerability-discovery-channels       获取渠道列表
POST   /api/v1/vulnerability-discovery-channels       创建渠道
PUT    /api/v1/vulnerability-discovery-channels/:id   更新渠道
DELETE /api/v1/vulnerability-discovery-channels/:id   删除渠道
```

### 系统端点
```
GET    /health    健康检查
GET    /version   版本信息
```

## 快速开始

### 🚀 一键启动（推荐）

使用统一管理脚本快速启动所有服务：

```bash
# 确保 Docker Desktop 已运行

# 一键启动（包括 MySQL + 数据库初始化 + 编译 + 启动后端）
./scripts/manage.sh start

# 等待启动完成，访问 API
curl http://localhost:8080/health
```

这将自动完成：
- ✅ 检查系统依赖（Docker、Go）
- ✅ 启动 MySQL 容器并等待就绪
- ✅ 初始化数据库（执行 mysql-init.sql）
- ✅ 创建测试用户和示例数据
- ✅ 安装 Go 依赖
- ✅ 编译后端代码
- ✅ 启动后端服务

**服务信息**：
- MySQL: `localhost:3306` (用户: root, 密码: securitycenter)
- API: `http://localhost:8080`
- 健康检查: `http://localhost:8080/health`

**常用命令**：
```bash
./scripts/manage.sh start    # 启动所有服务
./scripts/manage.sh stop     # 停止所有服务
./scripts/manage.sh restart  # 快速重启后端（开发时使用）
./scripts/manage.sh status   # 查看服务状态
./scripts/manage.sh logs     # 查看服务日志
./scripts/manage.sh clean    # 清理所有数据
```

---

### 📖 手动启动（可选）

如果需要手动控制每个步骤：

#### 1. 环境准备

**安装 Go**
```bash
# 确保安装 Go 1.21 或更高版本
go version
```

**启动 MySQL**
```bash
# 使用 Docker 启动 MySQL
make docker-up

# 或手动启动
docker-compose -f scripts/docker-compose.yml up -d
```

#### 2. 初始化数据库

```bash
# 执行数据库初始化脚本
make migrate
```

这将创建：
- `vuln_management` 数据库
- 所有必需的表结构
- 测试用户数据
- 系统默认配置（标签、渠道）
- 示例漏洞数据

#### 3. 配置文件

复制配置文件并根据需要修改：
```bash
cp configs/config.example.yaml configs/config.yaml
```

编辑 `configs/config.yaml`：
```yaml
database:
  dsn: "root:securitycenter@tcp(127.0.0.1:3306)/vuln_management?parseTime=true"
```

#### 4. 安装依赖

```bash
make install
```

#### 5. 运行服务

```bash
# 开发模式（支持热重载）
make dev

# 或直接运行
make run

# 或编译后运行
make build
./bin/vul-backend
```

服务默认启动在 `http://localhost:8080`

#### 6. 验证服务

```bash
# 健康检查
curl http://localhost:8080/health

# 获取版本信息
curl http://localhost:8080/version

# 获取漏洞列表
curl http://localhost:8080/api/v1/vulnerabilities

# 获取配置信息
curl http://localhost:8080/api/v1/vulnerabilities/config
```

## 项目结构

```
vul-backend/
├── cmd/
│   └── api/
│       └── main.go              # 程序入口
├── configs/
│   ├── config.yaml              # 配置文件
│   └── config.example.yaml      # 配置模板
├── internal/
│   ├── config/                  # 配置管理
│   │   ├── config.go
│   │   └── loader.go
│   ├── infra/                   # 基础设施
│   │   ├── mysql/
│   │   │   ├── mysql.go
│   │   │   └── migrate.go
│   │   └── redis/
│   ├── middleware/              # HTTP 中间件
│   │   ├── cors.go
│   │   ├── logger.go
│   │   ├── recovery.go
│   │   └── auth.go
│   ├── model/                   # 基础模型
│   │   ├── base.go
│   │   └── jsonb.go
│   ├── modules/
│   │   └── vuln/                # 漏洞管理模块
│   │       ├── handler/         # HTTP 处理层
│   │       │   ├── handler.go
│   │       │   ├── tag_handler.go
│   │       │   ├── discovery_channel_handler.go
│   │       │   └── helpers.go
│   │       ├── model/           # 数据模型
│   │       │   ├── vulnerability.go
│   │       │   ├── tag.go
│   │       │   └── discovery_channel.go
│   │       ├── repository/      # 数据访问层
│   │       │   ├── vulnerability_repository.go
│   │       │   ├── tag_repository.go
│   │       │   └── discovery_channel_repository.go
│   │       └── service/         # 业务逻辑层
│   │           ├── service.go
│   │           ├── tag_service.go
│   │           └── discovery_channel_service.go
│   └── pkg/                     # 通用工具
│       ├── logger/
│       │   └── logger.go
│       └── response/
│           └── response.go
├── scripts/
│   ├── manage.sh                # 统一管理脚本（启动/停止/重启/状态）
│   ├── mysql-init.sql           # 数据库初始化脚本
│   └── docker-compose.yml       # Docker 编排文件
├── go.mod                       # Go 模块定义
├── go.sum                       # Go 依赖校验
├── Makefile                     # 构建脚本
└── README.md                    # 项目文档
```

## 开发指南

### 🚀 快速开发工作流

```bash
# 1. 启动开发环境
./scripts/manage.sh start

# 2. 修改代码...

# 3. 快速重启测试（仅重启后端，不重启 MySQL）
./scripts/manage.sh restart

# 4. 查看日志排查问题
./scripts/manage.sh logs

# 5. 查看服务状态
./scripts/manage.sh status

# 6. 结束开发
./scripts/manage.sh stop
```

### 📖 详细开发文档

遵循以下分层架构进行开发：
- **Model 层** - 数据模型定义
- **Repository 层** - 数据库操作
- **Service 层** - 业务逻辑
- **Handler 层** - HTTP 处理

参考现有模块（Vulnerability、Tag、DiscoveryChannel）的代码风格和实现。

### 添加新功能

遵循分层架构：

1. **定义模型** (`internal/modules/vuln/model/`)
```go
type NewFeature struct {
    model.Base
    Name string `json:"name" gorm:"type:varchar(255);not null"`
}
```

2. **实现仓储** (`internal/modules/vuln/repository/`)
```go
type NewFeatureRepository interface {
    Create(ctx context.Context, feature *NewFeature) error
    FindByID(ctx context.Context, id uint64) (*NewFeature, error)
}
```

3. **编写服务** (`internal/modules/vuln/service/`)
```go
type NewFeatureService struct {
    repo repository.NewFeatureRepository
}
```

4. **创建处理器** (`internal/modules/vuln/handler/`)
```go
func (h *Handler) CreateFeature(c *gin.Context) {
    // 处理 HTTP 请求
}
```

5. **注册路由** (`cmd/api/main.go`)
```go
api.POST("/features", handler.CreateFeature)
```

### 数据库迁移

GORM 会自动迁移模型结构：
```go
// 在 internal/infra/mysql/migrate.go 中添加
func AutoMigrate(db *gorm.DB) error {
    return db.AutoMigrate(
        &vulnmodel.Vulnerability{},
        &vulnmodel.VulnerabilityTag{},
        // 添加新模型
        &vulnmodel.NewFeature{},
    )
}
```

### 配置管理

在 `internal/config/config.go` 中添加新配置：
```go
type Config struct {
    App      AppConfig      `mapstructure:"app"`
    HTTP     HTTPConfig     `mapstructure:"http"`
    Database DatabaseConfig `mapstructure:"database"`
    // 添加新配置
    NewConfig NewConfigStruct `mapstructure:"new_config"`
}
```

## API 使用示例

### 创建漏洞

```bash
curl -X POST http://localhost:8080/api/v1/vulnerabilities \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SQL 注入漏洞",
    "severity_level": "high",
    "status": "active",
    "application": "用户管理系统",
    "vulnerability_type": "SQL Injection",
    "discovery_channel": "white_box",
    "submitter_id": 1,
    "description": "在登录接口发现 SQL 注入漏洞"
  }'
```

### 查询漏洞列表

```bash
# 基本查询
curl "http://localhost:8080/api/v1/vulnerabilities?page=1&page_size=20"

# 按严重程度筛选
curl "http://localhost:8080/api/v1/vulnerabilities?severity=high,critical"

# 按状态筛选
curl "http://localhost:8080/api/v1/vulnerabilities?status=active"

# 多条件组合
curl "http://localhost:8080/api/v1/vulnerabilities?severity=high&status=active&page=1&page_size=10"
```

### 创建标签

```bash
curl -X POST http://localhost:8080/api/v1/vulnerability-tags \
  -H "Content-Type: application/json" \
  -d '{
    "name": "紧急修复",
    "category": "priority",
    "color": "#FF0000",
    "description": "需要立即修复的漏洞"
  }'
```

### 获取标签统计

```bash
curl http://localhost:8080/api/v1/vulnerability-tags/stats
```

## 测试

```bash
# 运行所有测试
make test

# 运行特定包的测试
go test -v ./internal/modules/vuln/service/

# 运行单个测试
go test -v ./internal/modules/vuln/service/ -run TestVulnerabilityService_List
```

## 部署

### Docker 部署

1. **构建镜像**
```bash
docker build -t vul-backend:latest .
```

2. **运行容器**
```bash
docker run -d \
  --name vul-backend \
  -p 8080:8080 \
  -e DATABASE_DSN="root:password@tcp(mysql:3306)/vuln_management?parseTime=true" \
  vul-backend:latest
```

### 二进制部署

```bash
# 编译
make build

# 复制文件到服务器
scp bin/vul-backend user@server:/opt/vul-backend/
scp -r configs user@server:/opt/vul-backend/

# 在服务器上运行
cd /opt/vul-backend
./vul-backend -config configs/config.yaml
```

### Systemd 服务

创建 `/etc/systemd/system/vul-backend.service`：

```ini
[Unit]
Description=Vulnerability Management Backend API
After=network.target mysql.service

[Service]
Type=simple
User=vul-backend
WorkingDirectory=/opt/vul-backend
ExecStart=/opt/vul-backend/vul-backend -config /opt/vul-backend/configs/config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
```

启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable vul-backend
sudo systemctl start vul-backend
sudo systemctl status vul-backend
```

## 环境变量

可以通过环境变量覆盖配置：

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `CONFIG_PATH` | 配置文件路径 | `./configs/config.yaml` |
| `APP_ENV` | 运行环境 | `development` |
| `HTTP_PORT` | HTTP 端口 | `8080` |
| `DB_DSN` | 数据库连接串 | - |
| `LOG_LEVEL` | 日志级别 | `info` |

## 性能调优

### 数据库连接池

在 `configs/config.yaml` 中调整：
```yaml
database:
  max_open_conns: 100      # 最大连接数
  max_idle_conns: 20       # 最大空闲连接
  conn_max_lifetime: 1h    # 连接最大生命周期
```

### HTTP 服务器

```yaml
http:
  read_timeout: 30s        # 读超时
  write_timeout: 30s       # 写超时
  shutdown_timeout: 10s    # 优雅关闭超时
```

## 监控和日志

### 日志配置

```yaml
log:
  level: info              # debug, info, warn, error
  format: json             # json 或 text
```

### 健康检查

```bash
# 简单检查
curl http://localhost:8080/health

# 详细检查（可扩展）
curl http://localhost:8080/health/detailed
```

## 常见问题

### Q: 如何快速启动项目？
A: 使用 `./scripts/manage.sh start` 一键启动所有服务。

### Q: 如何查看服务状态？
A: 使用 `./scripts/manage.sh status` 查看所有服务的运行状态。

### Q: 如何修改数据库连接？
A: 编辑 `configs/config.yaml` 中的 `database.dsn` 配置。

### Q: 如何启用调试日志？
A: 设置 `log.level: debug`，日志文件位于 `logs/app.log`。

### Q: 端口冲突怎么办？
A: 管理脚本会自动检测端口占用并提示处理。或手动修改 `configs/config.yaml` 中的 `http.port`。

### Q: 如何重置数据库？
A: 使用 `./scripts/manage.sh clean` 清理所有数据，然后重新 `./scripts/manage.sh start`。

### Q: 开发时如何快速重启？
A: 使用 `./scripts/manage.sh restart` 快速重启后端（不重启 MySQL）。

### Q: 如何查看日志？
A: 使用 `./scripts/manage.sh logs` 交互式选择查看不同服务的日志。

### Q: 支持 HTTPS 吗？
A: 建议在生产环境使用 Nginx 或云负载均衡器处理 HTTPS。