jeffusion/archived-gitea-ai-assistant
1
0
Fork 0
mirror of https://github.com/jeffusion/gitea-ai-assistant.git synced 2026-03-27 10:05:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README to reflect DB-first configuration model

Browse Source 
- Configuration Reference now shows only PORT/DATABASE_PATH/MASTER_KEY_PATH as env vars
- All other settings documented as Web UI configuration
- Installation steps simplified (no more .env editing for runtime config)
- Docker run command updated to use volume mount instead of --env-file
- k8s section simplified: only GITEA_ACCESS_TOKEN in Secret
This commit is contained in:
jeffusion
2026-03-05 11:35:47 +08:00
committed by 路遥知码力
parent 7a775ee9c5
commit 769517f7bf
3 changed files with 142 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
.env.example
View File

@@ -1,52 +1,8 @@
# Gitea配置
GITEA_API_URL=http://localhost:3000/api/v1
GITEA_ACCESS_TOKEN=your_gitea_token
# 自定义提示词
CUSTOM_SUMMARY_PROMPT=your_custom_prompt
CUSTOM_LINE_COMMENT_PROMPT=your_custom_prompt
# 飞书配置
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/your_webhook_token
FEISHU_WEBHOOK_SECRET=your_webhook_secret
# 应用配置 # 应用配置
PORT=3000 PORT=3000
# 建议使用以下命令生成一个安全的随机字符串作为webhook密钥: # DATABASE_PATH=./data/assistant.db # 可选，默认为 ./data/assistant.db
# 在Linux/Mac终端: openssl rand -hex 32 # MASTER_KEY_PATH=./data/master.key # 可选，默认为 ./data/master.key
# 或者在Node.js中: require('crypto').randomBytes(32).toString('hex')
WEBHOOK_SECRET=your_webhook_secret
ADMIN_PASSWORD=your_admin_password
# JWT_SECRET=auto_generated # 可选，不设置则自动生成
# LLM提供商配置（通过管理后台Web界面配置，不使用环境变量） # 所有其他配置（Gitea连接、飞书通知、Webhook密钥、管理员密码、审查引擎、记忆系统等）
# 启动服务后访问 http://localhost:3000 进行LLM提供商设置 # 均通过 Web 管理后台进行配置。
# 启动服务后访问 http://localhost:3000 进行配置。
# Agent审查配置（默认关闭，开启请设置为agent）
REVIEW_ENGINE=legacy
REVIEW_WORKDIR=/tmp/gitea-assistant
REVIEW_MAX_PARALLEL_RUNS=2
REVIEW_MAX_FILES_PER_RUN=200
REVIEW_MAX_FILE_CONTENT_CHARS=40000
REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE=0.8
REVIEW_ENABLE_HUMAN_GATE=true
REVIEW_ALLOWED_COMMANDS=git,rg,cat,sed,wc
REVIEW_COMMAND_TIMEOUT_MS=10000
# 向量记忆和学习系统配置（可选，第二阶段功能）
# Qdrant向量数据库URL（如果不配置则禁用记忆系统）
QDRANT_URL=http://localhost:6333
# 是否启用记忆系统（需要先配置QDRANT_URL）
ENABLE_MEMORY=false
# Few-shot学习示例数量（0-20）
FEW_SHOT_EXAMPLES_COUNT=10
# Reflection和Debate配置（可选，第三阶段功能）
# 是否启用Reflection自我批评机制（提升审查质量）
ENABLE_REFLECTION=false
# Reflection最大轮次（1-5）
MAX_REFLECTION_ROUNDS=2
# 是否启用Debate多代理辩论机制（提升高严重性问题准确性）
ENABLE_DEBATE=false
# Debate触发阈值（high=仅高严重性, medium=高和中等严重性）
DEBATE_THRESHOLD=high

138
README.md
View File

@@ -51,26 +51,22 @@ AI-powered code review assistant for Gitea. Automatically reviews Pull Requests
git clone https://github.com/user/gitea-ai-assistant.git git clone https://github.com/user/gitea-ai-assistant.git
cd gitea-ai-assistant cd gitea-ai-assistant
bun install bun install
cp .env.example .env
``` ```
### Configuration ### Configuration
Edit `.env` with your settings: Create a `.env` file with only infrastructure-level settings:
```bash ```bash
# Gitea # Server port (the only required setting)
GITEA_API_URL=https://your-gitea-instance.com/api/v1 PORT=3000
GITEA_ACCESS_TOKEN=your_gitea_token
# Security # Optional: custom data paths (defaults shown)
WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 # DATABASE_PATH=./data/assistant.db
# MASTER_KEY_PATH=./data/master.key
# Admin Dashboard
ADMIN_PASSWORD=your_admin_password
``` ```
> **Note**: LLM provider settings (API keys, models, endpoints) are configured through the Admin Dashboard Web UI, not environment variables. Access the dashboard at `http://your-server:3000` after starting the server. > **All other configuration** (Gitea connection, webhook secret, admin password, review engine, Feishu, memory settings, etc.) is managed through the **Admin Dashboard Web UI** at `http://your-server:3000`. On first boot, all settings are seeded with secure defaults automatically.
See [Configuration Reference](#configuration-reference) for all options. See [Configuration Reference](#configuration-reference) for all options.
@@ -86,7 +82,7 @@ bun run start # Production mode
**Option 1: Admin Dashboard (Recommended)** **Option 1: Admin Dashboard (Recommended)**
1. Access `http://your-server:3000` 1. Access `http://your-server:3000`
2. Log in with `ADMIN_PASSWORD` 2. Log in with the admin password (default: `password` — change it in the dashboard)
3. Click "Enable" on repositories to auto-configure webhooks 3. Click "Enable" on repositories to auto-configure webhooks
**Option 2: Manual Configuration** **Option 2: Manual Configuration**
@@ -94,80 +90,87 @@ bun run start # Production mode
In Gitea repository settings, add a webhook: In Gitea repository settings, add a webhook:
- **URL**: `http://your-server:3000/webhook/gitea` - **URL**: `http://your-server:3000/webhook/gitea`
- **Content Type**: `application/json` - **Content Type**: `application/json`
- **Secret**: Same as `WEBHOOK_SECRET` - **Secret**: Same as the Webhook Secret configured in the dashboard
- **Events**: "Pull Request" and "Status" - **Events**: "Pull Request" and "Status"
## Configuration Reference ## Configuration Reference
### Core Settings ### Environment Variables (Minimal)
Only infrastructure-level settings that must be known before the database is initialized:
| Variable | Description | Default | | Variable | Description | Default |
|----------|-------------|---------| |----------|-------------|---------|
| `GITEA_API_URL` | Gitea API endpoint | Required | | `PORT` | Server port | `5174` |
| `GITEA_ACCESS_TOKEN` | Token for code review (read + comment permissions) | Required | | `DATABASE_PATH` | SQLite database file path | `./data/assistant.db` |
| `GITEA_ADMIN_TOKEN` | Token for webhook management (optional) | - | | `MASTER_KEY_PATH` | Encryption master key file path | `./data/master.key` |
| `PORT` | Server port | `3000` |
| `WEBHOOK_SECRET` | Webhook signature secret | Required |
### LLM Provider Configuration ### Web UI Configuration (Admin Dashboard)
All runtime configuration is managed through the **Admin Dashboard** at `http://your-server:PORT`. Changes take effect immediately without restart.
On first boot with an empty database, all settings are seeded with secure defaults:
- `JWT_SECRET` and `WEBHOOK_SECRET` are auto-generated (64-char hex via `crypto.randomBytes`)
- `ADMIN_PASSWORD` defaults to `password` — **change this immediately**
#### Gitea
| Setting | Description |
|---------|-------------|
| Gitea API URL | Gitea API endpoint (e.g. `https://gitea.example.com/api/v1`) |
| Access Token | Token for code review (read + comment permissions) |
| Admin Token | Token for webhook management (optional) |
#### Security
| Setting | Description | Default |
|---------|-------------|---------|
| Webhook Secret | HMAC-SHA256 webhook signature secret | Auto-generated |
| Admin Password | Dashboard login password | `password` |
| JWT Secret | JWT signing secret | Auto-generated |
#### LLM Provider Configuration
LLM providers and models are configured exclusively through the **Admin Dashboard** Web UI: LLM providers and models are configured exclusively through the **Admin Dashboard** Web UI:
1. Access the dashboard at `http://your-server:3000` 1. Navigate to **LLM 配置** (LLM Configuration)
2. Navigate to **LLM 配置** (LLM Configuration) 2. Add your LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini)
3. Add your LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini) 3. Assign models to review roles (legacy, planner, specialist, judge, embedding)
4. Assign models to review roles (legacy, planner, specialist, judge, embedding)
> API keys are stored encrypted (AES-256-GCM) in a local SQLite database. > API keys are stored encrypted (AES-256-GCM) in the local SQLite database.
### Custom Prompts
| Variable | Description | #### Feishu Integration
|----------|-------------|
| `CUSTOM_SUMMARY_PROMPT` | Override the default summary review prompt |
| `CUSTOM_LINE_COMMENT_PROMPT` | Override the default line comment prompt |
### Admin Dashboard | Setting | Description |
|---------|-------------|
| Feishu Webhook URL | Feishu bot webhook URL |
| Feishu Webhook Secret | Feishu webhook secret (optional) |
| Variable | Description | Default | #### Agent Review Engine
|----------|-------------|---------|
| `ADMIN_PASSWORD` | Dashboard login password | `password` |
| `JWT_SECRET` | JWT signing secret | Auto-generated |
### Feishu Integration | Setting | Description | Default |
|---------|-------------|---------|
| Review Engine | Engine mode (`legacy` or `agent`) | `legacy` |
| Review Work Directory | Working directory for repo clones | `/tmp/gitea-assistant` |
| Max Parallel Runs | Max concurrent review tasks | `2` |
| Max Files per Run | Max files analyzed per review | `200` |
| Auto-publish Min Confidence | Min confidence score for auto-publish | `0.8` |
| Enable Human Gate | Require human approval before publishing | `true` |
| Variable | Description | #### Memory & Learning (Experimental)
|----------|-------------|
| `FEISHU_WEBHOOK_URL` | Feishu bot webhook URL |
| `FEISHU_WEBHOOK_SECRET` | Feishu webhook secret (optional) |
### Agent Review Engine
Enable with `REVIEW_ENGINE=agent` for advanced multi-agent reviews:
| Variable | Description | Default |
|----------|-------------|---------|
| `REVIEW_ENGINE` | Engine mode (`legacy` or `agent`) | `legacy` |
| `REVIEW_WORKDIR` | Working directory for repo clones | `/tmp/gitea-assistant` |
| `REVIEW_MAX_PARALLEL_RUNS` | Max concurrent tasks | `2` |
| `REVIEW_MAX_FILES_PER_RUN` | Max files per review | `200` |
| `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE` | Min confidence for auto-publish | `0.8` |
| `REVIEW_ENABLE_HUMAN_GATE` | Enable human approval | `true` |
### Memory & Learning (Experimental)
| Variable | Description | Default |
|----------|-------------|---------|
| `QDRANT_URL` | Qdrant vector database URL | - |
| `ENABLE_MEMORY` | Enable memory system | `false` |
| `ENABLE_REFLECTION` | Enable self-critique | `false` |
| `ENABLE_DEBATE` | Enable multi-agent debate | `false` |
| Setting | Description | Default |
|---------|-------------|---------|
| Qdrant URL | Qdrant vector database URL | - |
| Enable Memory | Enable memory system | `false` |
| Enable Reflection | Enable self-critique | `false` |
| Enable Debate | Enable multi-agent debate | `false` |
## Deployment ## Deployment
### Docker ### Docker
```bash ```bash
docker build -t gitea-assistant . docker build -t gitea-assistant .
docker run -d -p 3000:3000 --env-file .env gitea-assistant docker run -d -p 3000:3000 -v ./data:/app/data -e PORT=3000 gitea-assistant
``` ```
### Docker Compose ### Docker Compose
@@ -182,22 +185,21 @@ Kubernetes manifests are located in the `k8s/` directory.
**1. Configure Secrets** **1. Configure Secrets**
Encode your credentials as base64 and update `k8s/gitea-assistant.yaml`: Only the Gitea access token needs to be in the Secret (the only sensitive env-var-level setting):
```bash ```bash
echo -n "your_gitea_token" | base64 echo -n "your_gitea_token" | base64
echo -n "your_webhook_secret" | base64
echo -n "your_admin_password" | base64
``` ```
Update `GITEA_ACCESS_TOKEN` in `k8s/gitea-assistant.yaml`.
**2. Configure Application** **2. Configure Application**
Edit the ConfigMap in `k8s/gitea-assistant.yaml`: Edit the ConfigMap in `k8s/gitea-assistant.yaml`:
- Set `GITEA_API_URL` to your Gitea instance API endpoint - Set `GITEA_API_URL` to your Gitea instance API endpoint
- Adjust review engine settings as needed
> **Note**: LLM provider configuration is done through the Admin Dashboard after deployment. Ensure persistent storage is configured for the `/app/data` directory to retain LLM settings and encrypted API keys. > **Note**: All other settings (webhook secret, admin password, review engine, Feishu, etc.) are configured through the Admin Dashboard Web UI after deployment. They are auto-seeded on first boot. Ensure persistent storage is configured for the `/app/data` directory.
**3. Deploy** **3. Deploy**
```bash ```bash

134
docs/README.zh-CN.md
View File

@@ -51,26 +51,22 @@
git clone https://github.com/user/gitea-ai-assistant.git git clone https://github.com/user/gitea-ai-assistant.git
cd gitea-ai-assistant cd gitea-ai-assistant
bun install bun install
cp .env.example .env
``` ```
### 配置说明 ### 配置说明
编辑 `.env` 文件： 创建 `.env` 文件，仅填写基础设施级别的配置：
```bash ```bash
# Gitea # 服务端口（唯一必需的配置项）
GITEA_API_URL=https://your-gitea-instance.com/api/v1 PORT=3000
GITEA_ACCESS_TOKEN=your_gitea_token
# 安全 # 可选：自定义数据路径（以下为默认值）
WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32 # DATABASE_PATH=./data/assistant.db
# MASTER_KEY_PATH=./data/master.key
# 管理后台
ADMIN_PASSWORD=your_admin_password
``` ```
> **注意**: LLM 提供商设置（API 密钥、模型、端点）通过管理后台 Web 界面配置，而非环境变量。启动服务后，访问 `http://your-server:3000` 进行配置。 > **所有其他配置**（Gitea 连接、Webhook 密钥、管理员密码、审查引擎、飞书、记忆系统等）均通过 **Web 管理后台** 在 `http://your-server:3000` 进行配置。首次启动时，所有设置会自动以安全的默认值进行初始化。
完整配置项请参阅 [配置参考](#配置参考)。 完整配置项请参阅 [配置参考](#配置参考)。
@@ -86,7 +82,7 @@ bun run start # 生产模式
**方式一：管理后台（推荐）** **方式一：管理后台（推荐）**
1. 在浏览器中访问 `http://your-server:3000` 1. 在浏览器中访问 `http://your-server:3000`
2. 使用 `ADMIN_PASSWORD` 登录 2. 使用管理员密码登录（默认：`password`，请在后台及时修改）
3. 点击仓库对应的「启用」按钮自动配置 Webhook 3. 点击仓库对应的「启用」按钮自动配置 Webhook
**方式二：手动配置** **方式二：手动配置**
@@ -94,80 +90,87 @@ bun run start # 生产模式
在 Gitea 仓库设置中添加 Webhook： 在 Gitea 仓库设置中添加 Webhook：
- **URL**: `http://your-server:3000/webhook/gitea` - **URL**: `http://your-server:3000/webhook/gitea`
- **内容类型**: `application/json` - **内容类型**: `application/json`
- **密钥**: 与 `WEBHOOK_SECRET` 相同 - **密钥**: 与管理后台中配置的 Webhook 密钥相同
- **触发事件**: 「Pull Request」和「Status」 - **触发事件**: 「Pull Request」和「Status」
## 配置参考 ## 配置参考
### 核心配置 ### 环境变量（最小化）
仅包含数据库初始化前必须已知的基础设施级别配置：
| 变量 | 描述 | 默认值 | | 变量 | 描述 | 默认值 |
|------|------|--------| |------|------|--------|
| `GITEA_API_URL` | Gitea API 地址 | 必填 | | `PORT` | 服务端口 | `5174` |
| `GITEA_ACCESS_TOKEN` | 代码审查令牌（需要读取和评论权限） | 必填 | | `DATABASE_PATH` | SQLite 数据库文件路径 | `./data/assistant.db` |
| `GITEA_ADMIN_TOKEN` | Webhook 管理令牌（可选） | - | | `MASTER_KEY_PATH` | 加密主密钥文件路径 | `./data/master.key` |
| `PORT` | 服务端口 | `3000` |
| `WEBHOOK_SECRET` | Webhook 签名验证密钥 | 必填 |
### LLM 提供商配置 ### Web 界面配置（管理后台）
所有运行时配置均通过 **管理后台** `http://your-server:PORT` 进行管理，修改后立即生效，无需重启。
首次以空数据库启动时，所有设置会自动以安全默认值初始化：
- `JWT_SECRET` 和 `WEBHOOK_SECRET` 自动生成（通过 `crypto.randomBytes` 生成 64 位十六进制字符串）
- `ADMIN_PASSWORD` 默认为 `password`，**请立即修改**
#### Gitea
| 配置项 | 描述 |
|--------|------|
| Gitea API 地址 | Gitea API 端点（如 `https://gitea.example.com/api/v1`） |
| 访问令牌 | 代码审查令牌（需读取和评论权限） |
| 管理员令牌 | Webhook 管理令牌（可选） |
#### 安全
| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| Webhook 密钥 | HMAC-SHA256 Webhook 签名密钥 | 自动生成 |
| 管理员密码 | 后台登录密码 | `password` |
| JWT 密钥 | JWT 签名密钥 | 自动生成 |
#### LLM 提供商配置
LLM 提供商和模型通过**管理后台** Web 界面进行配置： LLM 提供商和模型通过**管理后台** Web 界面进行配置：
1. 访问管理后台 `http://your-server:3000` 1. 导航到 **LLM 配置** 页面
2. 导航到 **LLM 配置** 页面 2. 添加 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini）
3. 添加 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini） 3. 为审查角色分配模型（legacy、planner、specialist、judge、embedding）
4. 为审查角色分配模型（legacy、planner、specialist、judge、embedding）
> API 密钥使用 AES-256-GCM 加密存储在本地 SQLite 数据库中。 > API 密钥使用 AES-256-GCM 加密存储在本地 SQLite 数据库中。
### 自定义提示词
| 变量 | 描述 | #### 飞书集成
|------|------|
| `CUSTOM_SUMMARY_PROMPT` | 自定义总结审查提示词 |
| `CUSTOM_LINE_COMMENT_PROMPT` | 自定义行级评论提示词 |
### 管理后台 | 配置项 | 描述 |
|--------|------|
| 飞书 Webhook 地址 | 飞书机器人 Webhook URL |
| 飞书 Webhook 密钥 | 飞书 Webhook 密钥（可选） |
| 变量 | 描述 | 默认值 | #### Agent 审查引擎
|------|------|--------|
| `ADMIN_PASSWORD` | 后台登录密码 | `password` |
| `JWT_SECRET` | JWT 签名密钥 | 自动生成 |
### 飞书集成 | 配置项 | 描述 | 默认值 |
|--------|------|--------|
| 审查引擎 | 引擎模式（`legacy` 或 `agent`） | `legacy` |
| 工作目录 | 仓库克隆工作目录 | `/tmp/gitea-assistant` |
| 最大并发数 | 最大并发审查任务数 | `2` |
| 最大文件数 | 单次审查最大文件数 | `200` |
| 自动发布置信度 | 自动发布最小置信度 | `0.8` |
| 启用人工审批 | 发布前要求人工确认 | `true` |
| 变量 | 描述 | #### 记忆与学习（实验性）
|------|------|
| `FEISHU_WEBHOOK_URL` | 飞书机器人 Webhook 地址 |
| `FEISHU_WEBHOOK_SECRET` | 飞书 Webhook 密钥（可选） |
### Agent 审查引擎
设置 `REVIEW_ENGINE=agent` 启用多代理审查：
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `REVIEW_ENGINE` | 引擎模式（`legacy` 或 `agent`） | `legacy` |
| `REVIEW_WORKDIR` | 仓库克隆工作目录 | `/tmp/gitea-assistant` |
| `REVIEW_MAX_PARALLEL_RUNS` | 最大并发任务数 | `2` |
| `REVIEW_MAX_FILES_PER_RUN` | 单次审查最大文件数 | `200` |
| `REVIEW_AUTO_PUBLISH_MIN_CONFIDENCE` | 自动发布最小置信度 | `0.8` |
| `REVIEW_ENABLE_HUMAN_GATE` | 启用人工审批 | `true` |
### 记忆与学习（实验性）
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `QDRANT_URL` | Qdrant 向量数据库地址 | - |
| `ENABLE_MEMORY` | 启用记忆系统 | `false` |
| `ENABLE_REFLECTION` | 启用自我批评 | `false` |
| `ENABLE_DEBATE` | 启用多代理辩论 | `false` |
| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| Qdrant 地址 | Qdrant 向量数据库地址 | - |
| 启用记忆 | 启用记忆系统 | `false` |
| 启用反思 | 启用自我批评 | `false` |
| 启用辩论 | 启用多代理辩论 | `false` |
## 部署指南 ## 部署指南
### Docker ### Docker
```bash ```bash
docker build -t gitea-assistant . docker build -t gitea-assistant .
docker run -d -p 3000:3000 --env-file .env gitea-assistant docker run -d -p 3000:3000 -v ./data:/app/data -e PORT=3000 gitea-assistant
``` ```
### Docker Compose ### Docker Compose
@@ -182,12 +185,10 @@ Kubernetes 部署清单位于 `k8s/` 目录。
**1. 配置密钥** **1. 配置密钥**
将凭证编码为 base64 并更新 `k8s/gitea-assistant.yaml` 中的 Secret： 只需将 Gitea 访问令牌编码为 base64 并填入 `k8s/gitea-assistant.yaml`：
```bash ```bash
echo -n "your_gitea_token" | base64 echo -n "your_gitea_token" | base64
echo -n "your_webhook_secret" | base64
echo -n "your_admin_password" | base64
``` ```
**2. 配置应用** **2. 配置应用**
@@ -195,9 +196,8 @@ echo -n "your_admin_password" | base64
编辑 `k8s/gitea-assistant.yaml` 中的 ConfigMap： 编辑 `k8s/gitea-assistant.yaml` 中的 ConfigMap：
- 将 `GITEA_API_URL` 设置为你的 Gitea 实例 API 地址 - 将 `GITEA_API_URL` 设置为你的 Gitea 实例 API 地址
- 根据需要调整审查引擎配置
> **注意**: LLM 提供商配置通过部署后的管理后台进行。请确保为 `/app/data` 目录配置持久化存储，以保留 LLM 设置和加密的 API 密钥。 > **注意**: 所有其他设置（Webhook 密钥、管理员密码、审查引擎、飞书等）均在应用部署后通过管理后台进行配置，首次启动时自动初始化。请确保为 `/app/data` 目录配置持久化存储。
**3. 部署** **3. 部署**
```bash ```bash