diff --git a/.env.example b/.env.example index e61449e..8ccc118 100644 --- a/.env.example +++ b/.env.example @@ -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 进行配置。 diff --git a/README.md b/README.md index 14de08e..a16a756 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index b6cfb2b..8dc32b2 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -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