运行 Kodus API

本指南用于本地开发目的。对于生产部署，请参阅部署 Kodus 指南。

先决条件

Node.js（LTS 版本）
Docker
Yarn 或 NPM
LLM API 密钥

运行项目

自动设置（推荐）
手动设置

要进行快速自动设置，请使用我们的设置脚本：

git clone https://github.com/kodustech/kodus-ai.git
cd kodus-ai
yarn dev:first-run

此脚本将自动：

✅ 检查所有必需的依赖项（Node.js、Yarn、Docker、OpenSSL）
✅ 安装项目依赖项
✅ 创建和配置 .env 文件
✅ 自动生成所有必需的安全密钥
✅ 设置 Docker 网络
✅ 提供清晰的后续步骤

选择您的 LLM 模式（必需）

在启动服务之前选择一种模式并填写您的 .env。

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

后续步骤

基本设置：

yarn docker:start
yarn migrate:dev
yarn seed

带外部集成（webhook 等）：

yarn docker:start
yarn migrate:dev
yarn seed
yarn tunnel  # 为外部服务创建公共端点

如果您更喜欢手动配置所有内容：

1. 克隆仓库

git clone https://github.com/kodustech/kodus-ai.git

2. 安装依赖项

yarn install

3. 配置环境变量

cp .env.example .env

4. 选择您的 LLM 模式（必需）

在启动服务之前选择一种模式并填写您的 .env。

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

5. 生成安全密钥

在配置环境变量之前，您需要为 JWT 令牌和其他与安全相关的配置生成安全密钥：

# 用于大多数安全密钥（JWT 密钥等）
openssl rand -base64 32

# 用于加密密钥和代码管理密钥
openssl rand -hex 32

# 用于 webhook 令牌（URL 安全）
openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'

您需要为这些安全密钥生成值：

JWT_SECRET（使用 openssl rand -base64 32）
JWT_REFRESH_SECRET（使用 openssl rand -base64 32）
CODE_MANAGEMENT_SECRET（使用 openssl rand -hex 32）
CODE_MANAGEMENT_WEBHOOK_TOKEN（使用 openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'）

6. 设置 Docker 网络

创建所需的 Docker 网络：

docker network create kodus-backend-services || true
docker network create shared-network || true

7. 启动开发环境和隧道

使用 Docker 启动服务：

yarn docker:start
yarn tunnel

此命令启动：

Kodus API
PostgreSQL 数据库
MongoDB 数据库
所需的网络配置
为外部服务创建公共端点

8. 首次设置

如果这是您第一次运行该项目，请执行以下命令：运行数据库迁移：

yarn migrate:dev

填充初始数据：

yarn seed

8. 服务端点

访问服务：

API：http://localhost:3001
调试端口：9229

开发工作流程

基本本地开发

启动服务：yarn docker:start
运行迁移：yarn migrate:dev
加载种子数据：yarn seed
创建隧道：yarn tunnel（创建公共端点）
健康检查：yarn dev:health-check

带外部集成的开发

如果您需要测试与外部服务的集成（如 Git webhook）：

启动服务：yarn docker:start && yarn migrate:dev && yarn seed
创建隧道：yarn tunnel（创建公共端点）
更新 webhook URL：隧道命令会自动更新您的 .env
配置 Git 提供商：在 Git 提供商的 webhook 设置中使用隧道 URL
测试集成：触发 webhook 并监控日志

隧道优势：

在本地测试真实的 webhook 集成
调试外部服务通信
与团队成员共享您的开发环境
测试移动应用或其他外部客户端

故障排除

快速健康检查

yarn dev:health-check

此综合健康检查验证：

🐳 容器状态：Kodus API、PostgreSQL、MongoDB
🔌 端口可用性：API（3001）、PostgreSQL（5432）、MongoDB（27017）
🗄️ 数据库设置：迁移和种子数据
🌐 API 端点：健康端点和基本连接

手动验证

检查 API 健康：在浏览器中访问 http://localhost:3001/health
验证数据库连接：检查日志以查看成功的数据库连接
测试 webhook 端点：您的 Git 提供商 webhook 应指向 http://localhost:3001/[provider]/webhook

设置脚本问题

如果自动设置脚本（yarn dev:first-run）失败： 缺少依赖项：

# 检查是否安装了所有必需的工具
node --version
yarn --version
docker --version
openssl version

Docker 权限问题：

# 将您的用户添加到 docker 组（Linux/macOS）
sudo usermod -aG docker $USER
# 然后注销并重新登录

网络创建错误：

# 检查网络是否已存在
docker network ls | grep kodus
# 如果需要，删除冲突的网络
docker network rm kodus-backend-services shared-network

常见问题

端口冲突：

确保端口 3001（API）、5432（PostgreSQL）和 27017（MongoDB）可用
在启动 Kodus 之前停止使用这些端口的其他服务

环境变量未加载：

验证项目根目录中存在 .env 文件
检查变量赋值中是否没有尾随空格
确保所有必需的安全密钥都已正确生成

健康检查失败：

运行 yarn dev:health-check 以获取详细诊断
检查容器是否完全启动（在 yarn docker:start 后等待 1-2 分钟）
验证数据库迁移和种子数据是否已加载
使用 yarn docker:logs 检查 API 日志以查找启动错误

API 无响应：

容器启动后 API 需要时间才能完全初始化
检查迁移和种子数据是否已加载
验证 .env 文件是否包含所有必需的变量
运行健康检查以查看哪些特定组件失败

外部服务的 webhook 问题：

使用 yarn tunnel 为外部 webhook 创建公共端点
更新 Git 提供商的 webhook URL 以使用隧道 URL
测试 webhook 集成时确保隧道正在运行
检查隧道日志以查找连接问题

概念

本地快速开始

部署 Kodus

Git 提供商配置

运行 Kodus API

先决条件

运行项目

选择您的 LLM 模式（必需）

Model Configuration Guides

后续步骤

1. 克隆仓库

2. 安装依赖项

3. 配置环境变量

4. 选择您的 LLM 模式（必需）

Model Configuration Guides

5. 生成安全密钥

6. 设置 Docker 网络

7. 启动开发环境和隧道

8. 首次设置

8. 服务端点

开发工作流程

基本本地开发

带外部集成的开发

故障排除

快速健康检查

手动验证

设置脚本问题

常见问题

概念

本地快速开始

部署 Kodus

Git 提供商配置

​先决条件

​运行项目

​选择您的 LLM 模式（必需）

Model Configuration Guides

​后续步骤

​1. 克隆仓库

​2. 安装依赖项

​3. 配置环境变量

​4. 选择您的 LLM 模式（必需）

Model Configuration Guides

​5. 生成安全密钥

​6. 设置 Docker 网络

​7. 启动开发环境和隧道

​8. 首次设置

​8. 服务端点

​开发工作流程

​基本本地开发

​带外部集成的开发

​故障排除

​快速健康检查

​手动验证

​设置脚本问题

​常见问题

先决条件

运行项目

选择您的 LLM 模式（必需）

后续步骤

1. 克隆仓库

2. 安装依赖项

3. 配置环境变量

4. 选择您的 LLM 模式（必需）

5. 生成安全密钥

6. 设置 Docker 网络

7. 启动开发环境和隧道

8. 首次设置

8. 服务端点

开发工作流程

基本本地开发

带外部集成的开发

故障排除

快速健康检查

手动验证

设置脚本问题

常见问题