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
# 建议使用以下命令生成一个安全的随机字符串作为webhook密钥:
# 在Linux/Mac终端: openssl rand -hex 32
# 或者在Node.js中: require('crypto').randomBytes(32).toString('hex')
WEBHOOK_SECRET=your_webhook_secret
ADMIN_PASSWORD=your_admin_password
# JWT_SECRET=auto_generated # 可选，不设置则自动生成
# DATABASE_PATH=./data/assistant.db # 可选，默认为 ./data/assistant.db
# MASTER_KEY_PATH=./data/master.key # 可选，默认为 ./data/master.key
# LLM提供商配置（通过管理后台Web界面配置，不使用环境变量）
# 启动服务后访问 http://localhost:3000 进行LLM提供商设置
# 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
# 所有其他配置（Gitea连接、飞书通知、Webhook密钥、管理员密码、审查引擎、记忆系统等）
# 均通过 Web 管理后台进行配置。
# 启动服务后访问 http://localhost:3000 进行配置。

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
cd gitea-ai-assistant
bun install
cp .env.example .env
```
### Configuration
Edit `.env` with your settings:
Create a `.env` file with only infrastructure-level settings:
```bash
# Gitea
GITEA_API_URL=https://your-gitea-instance.com/api/v1
GITEA_ACCESS_TOKEN=your_gitea_token
# Server port (the only required setting)
PORT=3000
# Security
WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32
# Admin Dashboard
ADMIN_PASSWORD=your_admin_password
# Optional: custom data paths (defaults shown)
# DATABASE_PATH=./data/assistant.db
# MASTER_KEY_PATH=./data/master.key
```
> **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.
@@ -86,7 +82,7 @@ bun run start # Production mode
**Option 1: Admin Dashboard (Recommended)**
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
**Option 2: Manual Configuration**
@@ -94,80 +90,87 @@ bun run start # Production mode
In Gitea repository settings, add a webhook:
- **URL**: `http://your-server:3000/webhook/gitea`
- **Content Type**: `application/json`
- **Secret**: Same as `WEBHOOK_SECRET`
- **Secret**: Same as the Webhook Secret configured in the dashboard
- **Events**: "Pull Request" and "Status"
## Configuration Reference
### Core Settings
### Environment Variables (Minimal)
Only infrastructure-level settings that must be known before the database is initialized:
| Variable | Description | Default |
|----------|-------------|---------|
| `GITEA_API_URL` | Gitea API endpoint | Required |
| `GITEA_ACCESS_TOKEN` | Token for code review (read + comment permissions) | Required |
| `GITEA_ADMIN_TOKEN` | Token for webhook management (optional) | - |
| `PORT` | Server port | `3000` |
| `WEBHOOK_SECRET` | Webhook signature secret | Required |
| `PORT` | Server port | `5174` |
| `DATABASE_PATH` | SQLite database file path | `./data/assistant.db` |
| `MASTER_KEY_PATH` | Encryption master key file path | `./data/master.key` |
### 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:
1. Access the dashboard at `http://your-server:3000`
2. Navigate to **LLM 配置** (LLM Configuration)
3. Add your LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini)
4. Assign models to review roles (legacy, planner, specialist, judge, embedding)
1. Navigate to **LLM 配置** (LLM Configuration)
2. Add your LLM providers (OpenAI Compatible, OpenAI Responses API, Anthropic, Google Gemini)
3. Assign models to review roles (legacy, planner, specialist, judge, embedding)
> API keys are stored encrypted (AES-256-GCM) in a local SQLite database.
### Custom Prompts
> API keys are stored encrypted (AES-256-GCM) in the local SQLite database.
| Variable | Description |
|----------|-------------|
| `CUSTOM_SUMMARY_PROMPT` | Override the default summary review prompt |
| `CUSTOM_LINE_COMMENT_PROMPT` | Override the default line comment prompt |
#### Feishu Integration
### Admin Dashboard
| Setting | Description |
|---------|-------------|
| Feishu Webhook URL | Feishu bot webhook URL |
| Feishu Webhook Secret | Feishu webhook secret (optional) |
| Variable | Description | Default |
|----------|-------------|---------|
| `ADMIN_PASSWORD` | Dashboard login password | `password` |
| `JWT_SECRET` | JWT signing secret | Auto-generated |
#### Agent Review Engine
### 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 |
|----------|-------------|
| `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` |
#### Memory & Learning (Experimental)
| 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
### Docker
```bash
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
@@ -182,22 +185,21 @@ Kubernetes manifests are located in the `k8s/` directory.
**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
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**
Edit the ConfigMap in `k8s/gitea-assistant.yaml`:
- 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**
```bash

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

@@ -51,26 +51,22 @@
git clone https://github.com/user/gitea-ai-assistant.git
cd gitea-ai-assistant
bun install
cp .env.example .env
```
### 配置说明
编辑 `.env` 文件：
创建 `.env` 文件，仅填写基础设施级别的配置：
```bash
# Gitea
GITEA_API_URL=https://your-gitea-instance.com/api/v1
GITEA_ACCESS_TOKEN=your_gitea_token
# 服务端口（唯一必需的配置项）
PORT=3000
# 安全
WEBHOOK_SECRET=your_webhook_secret # openssl rand -hex 32
# 管理后台
ADMIN_PASSWORD=your_admin_password
# 可选：自定义数据路径（以下为默认值）
# DATABASE_PATH=./data/assistant.db
# MASTER_KEY_PATH=./data/master.key
```
> **注意**: 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`
2. 使用 `ADMIN_PASSWORD` 登录
2. 使用管理员密码登录（默认：`password`，请在后台及时修改）
3. 点击仓库对应的「启用」按钮自动配置 Webhook
**方式二：手动配置**
@@ -94,80 +90,87 @@ bun run start # 生产模式
在 Gitea 仓库设置中添加 Webhook：
- **URL**: `http://your-server:3000/webhook/gitea`
- **内容类型**: `application/json`
- **密钥**: 与 `WEBHOOK_SECRET` 相同
- **密钥**: 与管理后台中配置的 Webhook 密钥相同
- **触发事件**: 「Pull Request」和「Status」
## 配置参考
### 核心配置
### 环境变量（最小化）
仅包含数据库初始化前必须已知的基础设施级别配置：
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `GITEA_API_URL` | Gitea API 地址 | 必填 |
| `GITEA_ACCESS_TOKEN` | 代码审查令牌（需要读取和评论权限） | 必填 |
| `GITEA_ADMIN_TOKEN` | Webhook 管理令牌（可选） | - |
| `PORT` | 服务端口 | `3000` |
| `WEBHOOK_SECRET` | Webhook 签名验证密钥 | 必填 |
| `PORT` | 服务端口 | `5174` |
| `DATABASE_PATH` | SQLite 数据库文件路径 | `./data/assistant.db` |
| `MASTER_KEY_PATH` | 加密主密钥文件路径 | `./data/master.key` |
### 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 界面进行配置：
1. 访问管理后台 `http://your-server:3000`
2. 导航到 **LLM 配置** 页面
3. 添加 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini）
4. 为审查角色分配模型（legacy、planner、specialist、judge、embedding）
1. 导航到 **LLM 配置** 页面
2. 添加 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini）
3. 为审查角色分配模型（legacy、planner、specialist、judge、embedding）
> API 密钥使用 AES-256-GCM 加密存储在本地 SQLite 数据库中。
### 自定义提示词
| 变量 | 描述 |
|------|------|
| `CUSTOM_SUMMARY_PROMPT` | 自定义总结审查提示词 |
| `CUSTOM_LINE_COMMENT_PROMPT` | 自定义行级评论提示词 |
#### 飞书集成
### 管理后台
| 配置项 | 描述 |
|--------|------|
| 飞书 Webhook 地址 | 飞书机器人 Webhook URL |
| 飞书 Webhook 密钥 | 飞书 Webhook 密钥（可选） |
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `ADMIN_PASSWORD` | 后台登录密码 | `password` |
| `JWT_SECRET` | JWT 签名密钥 | 自动生成 |
#### Agent 审查引擎
### 飞书集成
| 配置项 | 描述 | 默认值 |
|--------|------|--------|
| 审查引擎 | 引擎模式（`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
```bash
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
@@ -182,12 +185,10 @@ Kubernetes 部署清单位于 `k8s/` 目录。
**1. 配置密钥**
将凭证编码为 base64 并更新 `k8s/gitea-assistant.yaml` 中的 Secret：
只需将 Gitea 访问令牌编码为 base64 并填入 `k8s/gitea-assistant.yaml`：
```bash
echo -n "your_gitea_token" | base64
echo -n "your_webhook_secret" | base64
echo -n "your_admin_password" | base64
```
**2. 配置应用**
@@ -195,9 +196,8 @@ echo -n "your_admin_password" | base64
编辑 `k8s/gitea-assistant.yaml` 中的 ConfigMap：
- 将 `GITEA_API_URL` 设置为你的 Gitea 实例 API 地址
- 根据需要调整审查引擎配置
> **注意**: LLM 提供商配置通过部署后的管理后台进行。请确保为 `/app/data` 目录配置持久化存储，以保留 LLM 设置和加密的 API 密钥。
> **注意**: 所有其他设置（Webhook 密钥、管理员密码、审查引擎、飞书等）均在应用部署后通过管理后台进行配置，首次启动时自动初始化。请确保为 `/app/data` 目录配置持久化存储。
**3. 部署**
```bash