安装 - Kodus

系统要求

推荐硬件

按默认 local 沙箱模式（kodus-graph + cross-file context 在 worker 容器内运行）调整大小。

CPU: 2+ 核心（约 100k LOC 以上的仓库推荐 4+ 核心）
RAM: 8GB+（在大型仓库上运行 local 沙箱时推荐 16GB）
存储: 60GB+ 可用空间（Postgres 保存 AST 图缓存；随仓库数量和 PR 量增长）

必需软件

Docker（最新稳定版）以及 Compose 插件
域名或固定 IP（如果您要从云端 Git 提供商（GitHub.com、GitLab.com 等）接收 webhook）

必需端口

默认主机端口映射 — 如果发生冲突，请在 .env 中调整。

3000 — Kodus Web App
3001 — API
3332 — Webhooks
5432 — PostgreSQL
27017 — MongoDB
5672, 15672, 15692 — RabbitMQ（AMQP、管理 UI、指标）
3101 — MCP Manager （仅当 API_MCP_SERVER_ENABLED=true 时）

服务

./scripts/install.sh 根据您的 .env 启动的内容。核心（始终运行）：

api — 主后端
worker — code review 作业
webhooks — Git 提供商 webhook 接收器
kodus-web — Next.js 前端
db_kodus_postgres、db_kodus_mongodb、rabbitmq — 本地基础设施。使用 USE_LOCAL_DB=false / USE_LOCAL_RABBITMQ=false 跳过以指向托管实例。

可选：

kodus-mcp-manager — Model Context Protocol broker。通过 API_MCP_SERVER_ENABLED=true 启用。请参阅 MCP Manager。
worker-analytics — Cockpit 摄取（DORA 指标、PR classifier）。 仅限自托管企业版，默认不连接。请参阅 Analytics Worker。

Code review 使用在沙箱中运行的 AST 图 + cross-file 上下文 — local（默认，在 worker 内运行）或 e2b（付费远程沙箱）。有关模式、缓存行为以及何时选择每种模式，请参阅 Sandbox & AST Graph。

如果您计划连接云端 Git 服务（GitHub、GitLab、Bitbucket）或云端 LLM 提供商（OpenAI、Anthropic 等），则需要互联网访问。 对于内网自托管的 Git 工具和本地/自托管 LLM，外网访问是可选的。

域名设置（可选）

If you're planning to integrate Kodus with cloud-based Git providers (GitHub, GitLab, or Bitbucket), you'll need public-facing URLs for both the Kodus Web App and its API. This allows your server to receive webhooks for proper Code Review functionality and ensures correct application behavior. We recommend setting up two subdomains:

One for the Web Application, e.g., kodus-web.yourdomain.com.
One for the API, e.g., kodus-api.yourdomain.com.

Webhook 由独立服务处理（端口 3332）。您可以选择：

使用独立的 webhook 子域名，例如 kodus-webhooks.yourdomain.com，或
继续使用 API 域名，并在反向代理中将 /github/webhook、/gitlab/webhook 等路径转发到 webhook 服务。

Both subdomains should have DNS A records pointing to your server's IP address. Later in this guide, we will configure a reverse proxy (Nginx) to route requests to these subdomains to the correct internal services. This setup is essential for full functionality, including webhooks and authentication.

Note: If you're only connecting to self-hosted Git tools on your network and do not require public access or webhooks, you might be able to use a simpler setup, but this guide focuses on public-facing deployments.

Setup

Clone the installer repository

git clone https://github.com/kodustech/kodus-installer.git
cd kodus-installer

Copy the example environment file

cp .env.example .env

Generate secure keys for the required environment variables

./generate-keys.sh

Edit the environment file

Edit .env with your values using your preferred text editor.

nano .env

详细说明请参见环境变量配置。

Run the installer

./scripts/install.sh

Success 🎉

When complete, Kodus Services should be running on your machine. You can verify your installation using the following script:

./scripts/doctor.sh

Access the web interface

Once you access the web interface for the first time, you'll need to:

Create your admin account - This will be the first user with full system access
Configure your Git provider - Connect GitHub, GitLab, or Bitbucket following the on-screen instructions
Select repositories for analysis - Choose which code repositories Kody will review

详细步骤请参见快速开始指南。

环境变量配置

使用此部分填写您的 .env。首先从公共 URL 开始，然后设置数据库和 RabbitMQ，最后添加特定于提供商的设置。

命名空间配置

这些设置定义了 Web 应用程序和 API 使用的公共 URL 和主机绑定。如果您不使用 MCP Manager，可以在此处跳过 MCP 条目和下面的完整块。

WEB_HOSTNAME_API="kodus-api.yourdomain.com"    # 公共 API 主机名（例如 kodus-api.yourdomain.com）
NEXTAUTH_URL="https://kodus-web.yourdomain.com" # Web 应用程序的完整公共基本 URL（例如 https://kodus-web.yourdomain.com）
API_HOST=0.0.0.0                              # API 主机（本地开发使用 0.0.0.0）

# 仅在您想使用 MCP 功能时需要。
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101 # MCP Manager URL
API_KODUS_MCP_SERVER_URL=http://kodus-api.yourdomain.com/mcp # Kodus MCP Server URL

LLM 提供商配置

API_LLM_PROVIDER_MODEL="gpt-5"     # 您想要使用的模型
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # 您的 API 提供商 URL
API_OPEN_AI_API_KEY="your-api-key"          # 您的 API 提供商密钥

查看我们的模型特定指南，获取热门提供商（如 Novita、OpenAI、Anthropic 等）的详细设置说明。

数据库配置

默认情况下，使用本地容器运行 Postgres 和 MongoDB。更新凭据以符合您的安全要求。

# 使用本地容器运行 Postgres 和 MongoDB
USE_LOCAL_DB=true

# PostgreSQL 设置
API_DATABASE_ENV="development"                # development, production, test
API_PG_DB_HOST=db_kodus_postgres              # PostgreSQL 主机
API_PG_DB_PORT=5432                          # PostgreSQL 端口
API_PG_DB_USERNAME=kodusdev                  # 数据库用户名
API_PG_DB_PASSWORD=                          # 数据库密码
API_PG_DB_DATABASE=kodus_db                  # 数据库名称

# MongoDB 设置
API_MG_DB_HOST=db_kodus_mongodb              # MongoDB 主机
API_MG_DB_PORT=27017                         # MongoDB 端口
API_MG_DB_USERNAME=kodusdev                  # 数据库用户名
API_MG_DB_PASSWORD=                          # 数据库密码
API_MG_DB_DATABASE=kodus                     # 数据库名称
API_MG_DB_PRODUCTION_CONFIG=''               # 其他生产设置

# SSL — 本地 Postgres 容器不支持 SSL。该全局开关覆盖所有数据源
# （default + analytics）。如果保持 false，api 会陷入 SSL 重试连接循环。
API_DATABASE_DISABLE_SSL=true                # 为本地数据库禁用 SSL

对于内置数据库，可将 API_PG_DB_PASSWORD 和 API_MG_DB_PASSWORD 留空并运行 ./scripts/generate-secrets.sh 来生成，或自行设置。对于外部数据库，请使用现有数据库的密码。

RabbitMQ 配置

2.0 需要 RabbitMQ。保持 URI 与以下值同步。

# RabbitMQ 配置
USE_LOCAL_RABBITMQ=true
RABBITMQ_HOSTNAME=rabbitmq                   # Docker 网络中的 RabbitMQ 主机名
RABBITMQ_DEFAULT_USER=kodus                  # RabbitMQ 用户（在生产环境中更改）
RABBITMQ_DEFAULT_PASS=kodus                  # RabbitMQ 密码（在生产环境中更改）

# 保持 URI 与上面的用户、密码和 vhost 同步
API_RABBITMQ_URI=amqp://kodus:kodus@rabbitmq:5672/kodus-ai # RabbitMQ 连接 URI
API_RABBITMQ_ENABLED=true                    # RabbitMQ 是必需的

Worker 配置

Worker 容器需要一个角色来确定处理哪种工作负载。Self-hosted 仅运行代码审查角色；analytics 角色仅适用于云端。

如果将 WORKER_ROLE 留空，worker 会在启动时崩溃。由于 workflow.jobs.* 队列是 worker 首次连接时创建的，worker 崩溃后 api 和 webhooks 会对每个 webhook 事件抛出 QueueBind 404 错误。

# Worker 角色 — 必填。Self-hosted = code-review。
WORKER_ROLE=code-review

Git 提供商配置

选择并配置您首选的 Git 提供商。您可以设置一个或多个提供商；对于基本的基于令牌的身份验证，您只需要 webhook URL。

Webhook 由独立服务处理（端口 3332）。Webhook URL 必须指向该服务。您可以使用独立的 webhook 域名，或继续使用 API 域名并在反向代理中将 /.../webhook 路径转发到 webhook 服务。如果您使用 GitHub 或 GitLab OAuth，请参见 GitHub OAuth App 或 GitLab OAuth App。如需 GitHub App 设置，请参见 GitHub App。

Github
GitLab
Bitbucket
Azure DevOps

# 基于令牌的身份验证所需
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"          # Webhook URL（使用 webhook 域名，或在代理转发到 Webhooks 服务时使用 API 域名）

# 基于令牌的身份验证所需
API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"          # Webhook URL（使用 webhook 域名，或在代理转发到 Webhooks 服务时使用 API 域名）

# 基于令牌的身份验证所需
GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"    # Webhook URL（使用 webhook 域名，或在代理转发到 Webhooks 服务时使用 API 域名）

# 基于令牌的身份验证所需
GLOBAL_AZURE_REPOS_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/azure-repos/webhook"    # Webhook URL（使用 webhook 域名，或在代理转发到 Webhooks 服务时使用 API 域名）

MCP Manager 配置

仅在您想使用 MCP Manager 时需要。

MCP Manager 是将 Kody 连接到外部工具并在插件屏幕中公开这些工具的服务。查看我们的 MCP Manager 文档了解更多信息。

API_MCP_SERVER_ENABLED=false # 如果您想使用 MCP Manager，请更改为 true
---
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101
API_KODUS_MCP_SERVER_URL=http://localhost:3001/mcp

# MCP Manager 配置
API_MCP_MANAGER_LOG_LEVEL=info
API_MCP_MANAGER_PORT=3101
API_MCP_MANAGER_NODE_ENV=development
API_MCP_MANAGER_DATABASE_ENV=development
API_MCP_MANAGER_CORS_ORIGINS=*
API_MCP_MANAGER_JWT_SECRET=
API_MCP_MANAGER_MCP_PROVIDERS=kodusmcp,custom
API_MCP_MANAGER_REDIRECT_URI=http://localhost:3000/setup/mcp/oauth
API_MCP_MANAGER_PG_DB_SCHEMA=mcp-manager
API_MCP_MANAGER_ENCRYPTION_SECRET=

外部服务配置（可选）

这些服务是可选的，但能显著提升 Kodus 的代码审查质量。每个服务都需要您创建账号并生成 API 密钥。

E2B — 代码执行沙箱

E2B 提供安全的沙箱环境，Kodus 用它在审查过程中运行和验证代码。

在 e2b.dev 创建账号
在您的控制台中生成 API 密钥
添加到您的 .env：

API_E2B_KEY=your-e2b-api-key

MorphLLM — 代码编辑模型

MorphLLM 是专为快速、精准代码编辑设计的模型。Kodus 用它更精确地应用审查建议。

在 morphllm.com 创建账号
在您的控制台中生成 API 密钥
添加到您的 .env：

API_MORPHLLM_API_KEY=your-morphllm-api-key

需要帮助？

与我们的创始人安排通话，获取部署帮助。

从我们的社区获取帮助

加入我们的社区以获取部署帮助。

概念

本地快速开始

使用 Docker 部署

使用 Kubernetes 部署

Git 提供商配置

安装

系统要求

域名设置（可选）

Setup

环境变量配置

命名空间配置

LLM 提供商配置

数据库配置

RabbitMQ 配置

Worker 配置

Git 提供商配置

MCP Manager 配置

外部服务配置（可选）

需要帮助？

从我们的社区获取帮助

​系统要求

​域名设置（可选）

​Setup

​环境变量配置

​命名空间配置

​LLM 提供商配置

​数据库配置

​RabbitMQ 配置

​Worker 配置

​Git 提供商配置

​MCP Manager 配置

​外部服务配置（可选）

需要帮助？

从我们的社区获取帮助

系统要求

域名设置（可选）

Setup

环境变量配置

命名空间配置

LLM 提供商配置

数据库配置

RabbitMQ 配置

Worker 配置

Git 提供商配置

MCP Manager 配置

外部服务配置（可选）