DeepWiki-Open本地构建指南：从源码编译到运行的完整流程

项目简介

DeepWiki-Open是一款AI驱动的Wiki生成工具，能够为任何GitHub、GitLab或BitBucket仓库自动创建美观、交互式的文档。只需输入仓库名称，DeepWiki就能分析代码结构、生成全面文档、创建可视化图表并组织成易于导航的Wiki系统。

环境准备

硬件要求

• CPU: 4核及以上
• 内存: 8GB及以上
• 硬盘: 至少10GB可用空间
• 网络: 能够访问Git仓库和模型服务

软件依赖

• Git
• Python 3.8+
• Node.js 18+
• npm或yarn
• Docker和Docker Compose (可选)

源码获取

克隆仓库

# 克隆DeepWiki-Open仓库
git clone https://gitcode.com/gh_mirrors/de/deepwiki-open.git
cd deepwiki-open

配置环境变量

创建.env文件

在项目根目录创建.env文件，添加必要的API密钥和配置：

# 创建.env文件
echo "GOOGLE_API_KEY=your_google_api_key" > .env
echo "OPENAI_API_KEY=your_openai_api_key" >> .env
# 可选：使用Google AI嵌入模型替代OpenAI（推荐配合Google模型使用）
echo "DEEPWIKI_EMBEDDER_TYPE=google" >> .env
# 可选：添加OpenRouter API密钥
echo "OPENROUTER_API_KEY=your_openrouter_api_key" >> .env
# 可选：添加Ollama主机地址（如非本地）
echo "OLLAMA_HOST=your_ollama_host" >> .env

完整的环境变量说明可参考项目文档：README.md

构建与运行方式

方式一：使用Docker Compose（推荐）

Docker方式可以简化部署流程，避免环境依赖问题：

# 使用Docker Compose启动服务
docker-compose up

Docker配置文件：docker-compose.yml

方式二：手动构建与运行

后端API服务

# 安装Python依赖
pip install -r api/requirements.txt

# 启动API服务器
python -m api.main

后端API源码：api/main.py

前端Web应用

# 安装JavaScript依赖
npm install
# 或
yarn install

# 启动开发服务器
npm run dev
# 或
yarn dev

前端主页面代码：src/app/page.tsx

项目结构解析

DeepWiki-Open采用前后端分离架构，主要目录结构如下：

deepwiki/
├── api/                  # 后端API服务器
│   ├── main.py           # API入口点
│   ├── api.py            # FastAPI实现
│   ├── rag.py            # 检索增强生成
│   ├── data_pipeline.py  # 数据处理工具
│   └── requirements.txt  # Python依赖
│
├── src/                  # 前端Next.js应用
│   ├── app/              # Next.js应用目录
│   │   └── page.tsx      # 主应用页面
│   └── components/       # React组件
│       └── Mermaid.tsx   # Mermaid图表渲染器
│
├── public/               # 静态资源
├── package.json          # JavaScript依赖
└── .env                  # 环境变量（需创建）

详细的项目结构可参考项目结构说明

运行验证

启动服务后，打开浏览器访问以下地址验证是否运行成功：

• Web界面：http://localhost:3000
• API服务：http://localhost:8001

成功运行后，您将看到DeepWiki的主界面，可以输入GitHub仓库URL开始生成Wiki文档。

高级配置

模型选择配置

DeepWiki支持多种AI模型提供商，包括Google、OpenAI、OpenRouter、Azure OpenAI和本地Ollama模型。模型配置文件位于：

• 生成器配置：api/config/generator.json
• 嵌入模型配置：api/config/embedder.json

使用本地Ollama模型

如果希望完全在本地运行，可使用Ollama模型：

# 在.env文件中添加
DEEPWIKI_EMBEDDER_TYPE=ollama
OLLAMA_HOST=http://localhost:11434

Ollama详细配置指南：Ollama-instruction.md

故障排除

常见问题解决

1. API密钥错误：检查.env文件中的API密钥是否正确配置
2. 依赖安装问题：确保Python和Node.js版本满足要求
3. 端口冲突：修改环境变量中的PORT和SERVER_BASE_URL解决端口冲突
4. 日志查看：API服务日志默认位于api/logs/application.log

开启调试日志

如需详细调试信息，可在.env文件中添加日志配置：

LOG_LEVEL=DEBUG
LOG_FILE_PATH=./debug.log

日志配置代码：api/logging_config.py

总结

通过本指南，您已了解如何从源码构建和运行DeepWiki-Open。无论是使用Docker快速部署，还是手动构建进行二次开发，DeepWiki都提供了灵活的选项。现在您可以开始体验AI驱动的智能Wiki生成功能，为您的项目创建专业的文档。