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 文件，配置以下内容：

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）

# Windows
install.bat

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

方式 B：Docker 部署

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

# 查看日志
docker-compose logs -f

步骤 3：启动服务

# 激活虚拟环境（如果使用虚拟环境）
# 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. 飞书群聊收到通知

测试手动扫描

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 代码检查

配置文件选项

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 凭证：

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/                # 报告输出