add web
This commit is contained in:
Dang Zerong
230
快速开始指南.md
Normal file
230
快速开始指南.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 快速开始指南
|
||||
|
||||
本文档将帮助你快速部署 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/ # 报告输出
|
||||
```
|
||||
Reference in New Issue
Block a user