code_scan/快速开始指南.md

# 快速开始指南

本文档将帮助你快速部署 AI Code Quality Scanner 并配置 Gitea Webhook 和飞书通知。

## 环境要求

- Python 3.8+
- Git
- Node.js 和 npm（用于 JavaScript/TypeScript 扫描，可选）
- Docker 和 Docker Compose（可选，用于容器化部署）

## 步骤 1：配置修改

### 修改 `config.yaml`

首先编辑 `config.yaml` 文件，配置以下内容：

```yaml
server:
  host: "0.0.0.0"
  port: 5000  # Webhook 服务端口

gitea:
  base_url: "http://服务器IP:3000"  # 你的 Gitea 地址
  webhook_secret: "your_secret_key"  # Webhook 签名密钥

feishu:
  webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # 飞书 Webhook 地址
  secret: ""  # 飞书签名密钥（可选）
```

### 获取飞书 Webhook 地址

1. 打开飞书群聊
2. 点击右上角「...」→「设置」→「群机器人」
3. 点击「添加机器人」→「自定义机器人」
4. 设置机器人名称，点击「添加」
5. 复制 Webhook 地址
6. （可选）开启「签名校验」，复制 secret

### 获取 Gitea Webhook 密钥

1. 在 Gitea 仓库页面，点击「仓库设置」→「Webhooks」
2. 点击「添加 Webhook」→「Gitea」
3. 填写以下信息：
   - 目标 URL: `http://你的服务器IP:5000/webhook/gitea`
   - 密钥: 自定义一个密钥（如 `my_secret_key`），需要与 config.yaml 中的 `webhook_secret` 一致
4. 点击「添加 Webhook」

## 步骤 2：安装依赖

### 方式 A：本地安装（Windows/Mac/Linux）

```bash
# Windows
install.bat

# Mac/Linux
chmod +x install.sh
./install.sh
```

### 方式 B：Docker 部署

```bash
# 构建并运行
docker-compose up -d

# 查看日志
docker-compose logs -f
```

## 步骤 3：启动服务

```bash
# 激活虚拟环境（如果使用虚拟环境）
# Windows
call venv\Scripts\activate.bat

# Mac/Linux
source venv/bin/activate

# 启动服务
python app.py
```

服务启动后，访问 `http://localhost:5000` 可以看到健康检查响应。

## 步骤 4：测试

### 测试 Webhook

在 Gitea 仓库中进行一次代码提交，应该能看到：

1. 服务端日志显示收到 Webhook 请求
2. 代码被克隆到临时目录
3. 扫描工具运行
4. 飞书群聊收到通知

### 测试手动扫描

```bash
curl -X POST http://localhost:5000/scan/manual \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/username/repo.git", "branch": "main"}'
```

## 配置说明

### 扫描工具说明

| 工具 | 语言 | 功能 |
|------|------|------|
| Pylint | Python | 代码风格和错误检查 |
| Flake8 | Python | Python 代码检查 |
| Bandit | Python | 安全漏洞扫描 |
| ESLint | JavaScript/TypeScript | JS/TS 代码检查 |

### 配置文件选项

```yaml
server:
  host: "0.0.0.0"      # 监听地址
  port: 5000           # 监听端口
  debug: true          # 调试模式

gitea:
  base_url: "http://localhost:3000"   # Gitea 地址
  webhook_secret: "secret"             # Webhook 签名密钥

feishu:
  webhook_url: "https://..."           # 飞书 Webhook
  secret: ""                           # 飞书签名密钥

scanner:
  languages:
    - python
    - javascript
    - typescript
  max_issues: 10          # 最大问题数量
  detailed: true          # 详细扫描模式
  temp_clone_dir: "/tmp/code_scanner_clones"  # 临时目录

report:
  output_dir: "./reports"    # 报告保存目录
  keep_files: true           # 是否保留报告文件
```

## 常见问题

### Q: 扫描时间很长怎么办？

A: 系统会浅克隆仓库（只获取最新提交），首次扫描后会有缓存。如果仍需优化，可以：
- 减少扫描的文件类型
- 调整 `max_issues` 参数

### Q: 飞书消息发送失败？

A: 检查：
1. Webhook 地址是否正确
2. 是否开启了签名校验（如果开启了，需要配置 secret）
3. 网络是否可达

### Q: 扫描不到代码？

A: 检查：
1. 仓库 URL 是否可公开访问
2. 私有仓库需要配置 Git 凭证
3. 确认分支名称正确

### Q: 如何访问 Gitea 私有仓库？

A: 在环境变量中配置 Git 凭证：
```bash
export GIT_USERNAME=your_username
export GIT_PASSWORD=your_password
```

或者在 Git 克隆 URL 中包含凭证：
```
http://username:password@gitea-server.com/user/repo.git
```

## 系统架构图

```
用户提交代码
    │
    ▼
Gitea Webhook ──────────────────────┐
    │                                │
    ▼                                │
Webhook 服务                        │
(Flask :5000)                       │
    │                                │
    ├──────────┬──────────┬─────────┘
    ▼          ▼          ▼
 Python    JS/TS     Security
 Scanner   Scanner    Scanner
    │          │          │
    └──────────┴──────────┘
              │
              ▼
        Report Generator
        (Markdown 报告)
              │
              ▼
         Feishu Bot
         (发送通知)
```

## 目录结构

```
code-scanner/
├── app.py                    # 主应用
├── config.yaml               # 配置文件
├── requirements.txt           # 依赖
├── Dockerfile               # Docker 镜像
├── docker-compose.yml       # Docker Compose
├── install.bat              # Windows 安装脚本
├── install.sh              # Linux 安装脚本
├── README.md               # 项目说明
├── 快速开始指南.md           # 本文档
├── webhook/                 # Webhook 处理
├── scanner/                 # 代码扫描器
├── report/                  # 报告生成
├── notify/                  # 飞书通知
└── reports/                # 报告输出
```